supranode.yaml
reference
The supranode.yaml
configuration file enables you to configure and override Supranode’s default behaviour within your project.
Configuration files can be as simple as:
build:
run: npm dist
artifacts:
app: _dist
or more complex like:
build:
env:
NODE_ENV: production
PRICING_URL: http://${{ vars.MY_DOMAIN }}/pricing
steps:
- name: Install dependencies
run: npm install
- name: Run tests
run: npm test
- name: Lint
run: npm run lint
if: environment.codeline == 'refs/heads/main'
continue_on_failure: true
- name: Generate website
run: npm run dist
env:
SECRET_KEY: ${{ secrets.SECRET_KEY }}
artifacts:
website: dist
doc: doc
preview: |
'[skip preview]' not in build.commit_message and
'[preview skip]' not in build.commit_message and
'[no preview]' not in build.commit_message
promote: environment.primary
routes:
- match: starts_with(request.path, '/doc/')
origin: doc
- origin: website
middlewares:
- force_https
- force_trailing_slash
- match: preview
script: http_basic_auth(vars.AUTH_USERNAME, secrets.AUTH_PASSWORD)
Here is the list of keywords:
build
build.artifacts
build.artifacts.<artifact name>
build.env
build.run
build.steps
build.steps[*]
build.steps[*].continue_on_failure
build.steps[*].env
build.steps[*].if
build.steps[*].name
build.steps[*].run
if
middlewares
middlewares[*]
middlewares[*].break
middlewares[*].match
middlewares[*].script
preview
promote
routes
routes[*].match
routes[*].origin
Keywords
build
Defines how your website is built.
build.artifacts
Defines the artifacts that are generated during the build phase.
build.artifacts.<artifact name>
Defines an artifact. The key is expected to be the artifact name, and the value the relative path where the artifact is located. For example:
build:
run: ...
artifacts:
website: _site
docs: doc
marketing: marketing
Artifact names must follow the format ^[A-Za-z](?:[A-Za-z\d_])*$
. Artifact names
must be unique per deploy pipeline.
build.env
Defines the environment variables available to the all steps. You can also set variables that are only available to a
single step. See build.steps[*].env
for more information.
When more than one environment variable is defined with the same name, Supranode uses the most specific variable. For example, an environment variable defined in a step will override environment variables defined here.
The value accepts a embedded expression, and has access to the global context and deployment pipeline context.
See the defaul build environment variables
build.run
Alias for build.steps[*].run
. See build.steps[*].run
for more information.
build:
run: npm install
is equivalent to:
build:
steps:
- run: npm install
build.steps
A build job contains a sequence of tasks called steps, which can run commands. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps.
build.steps[*]
Alias for build.steps[*].run
. See build.steps[*].run
for more information.
build:
steps:
- npm install
is equivalent to:
build:
steps:
- run: npm install
build.steps[*].continue_on_failure
Prevents a build job from failing when a step fails. Set to true
to allow a job to pass when this step fails.
Expects an expression and has access to the global context and deployment pipeline context.
build.steps[*].env
Defines the environment variables available to this step. You can also set variables for the entire build. See build.env
for more information.
When more than one environment variable is defined with the same name, Supranode uses the most specific variable. For example, an environment variable defined in a step will override environment variables defined here.
The value accepts a embedded expression, and has access to the global context and deployment pipeline context.
build.steps[*].if
You can use the if
conditional to prevent a step from running unless a condition is met. Expects an expression and has access to the global context.
build.steps[*].name
A name for your step to display on Supranode.
build.steps[*].run
Runs command-line programs using the operating system’s shell. If you do not provide a name, the step name will default to the text specified in the run command.
Commands run using non-login shells by default.
Each run keyword represents a new process and shell in the runner environment.
A single-line command:
- name: Install Dependencies
run: npm install
A multi-line command:
- name: Clean install dependencies and build
run: |
npm ci
npm run build
Multiple commands:
- name: Clean install dependencies and build
run:
- npm ci
- npm run build
if
You can use the if
conditional to prevent a deployment pipeline from running unless a condition is met. Expects an expression and has access to the global context
.
if: |
build.codeline == 'refs/heads/main' and
'[skip build]' not in build.commit_message and
'[build skip]' not in build.commit_message and
'[no build]' not in build.commit_message
middlewares
Supranode allows you to apply middlewares to apply logic to handling of the request before routing them to the proper origin. Middleware expressions allow you to do different things, like forcing HTTPS, or applying basic authentication.
middlewares[*]
Alias for middlewares[*].script
. See middlewares[*].script
for more information.
middlewares:
- http_basic_auth(secret.USERNAME, secrets.PASSWORD)
is equivalent to:
middlewares:
- script: http_basic_auth(secret.USERNAME, secrets.PASSWORD)
middlewares[*].script
The middleware expression that allow you to apply logic to handling of the request before routing them to the proper origin. Middleware expressions allow you to do different things, like forcing HTTPS, or applying basic authentication.
A single-line script:
middlewares:
- script: force_https
- script: http_basic_auth('supranode', vars.PASSWORD)
Multiple scripts:
middlewares:
- script:
- force_https
- http_basic_auth('supranode', vars.PASSWORD)
middlewares[*].break
You can use the break
conditional to prevent the middleware chain from continuing running unless a condition is met. Expects an expression and has access to the global context, the deployment pipeline context, and the request context.
middlewares[*].match
You can use the match
conditional to prevent a middleware from being applied unless a condition is met. Expects an expression and has access to the global context, the deployment pipeline context, and the request context.
preview
You can use the preview
conditional to prevent a deployment preview from being created unless a condition is met. Expects an expression and has access to the global context and the deployment pipeline context.
promote
You can use the promote
conditional to prevent a deployment from being promoted unless a condition is met. Expects an expression and has access to the global context and the deployment pipeline context.
routes
Supranode allows you to define custom routing logic.
routes[*].match
You can use the match
conditional to prevent a route from being applied unless a condition is met. Expects an expression and has access to the global context, the deployment pipeline context, and the request context.
routes[*].origin
The artifact name the request should be routed to.
Expressions
You can use expressions to programmatically set values or conditions in configuration files. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. See contexts for more information about contextual information.
Literals
You can use boolean (true
, false
), number (integers 1
, and floats 2.3
), string ("hello world"
or 'hello world'
), and list ([1, true, 'go!']
) data types.
Operators
()
- Logical grouping..
- Dot operator. To access values in a map[]
- Indexing and map access (request.headers[0]['content-type']
)+
,-
,*
- Arithmetic operators, for example1 + 2
,3 - 2
,2 * 2
,-3
==
,!=
,>
,>=
,<
,<=
- Comparison operatorsand
,or
,not
- Strict logical operators. They expect booleans as arguments.&&
,||
,!
- Non-strict logical operators.<>
- String concatenation operator, for example'/api/v1/' <> request.path
. Null values are converted into empty strings.in
- String or list inclusion, or key existence in map values, for example'[skip preview]' in build.commit_message
,environment.name in ['production', 'staging']
or'MY_VAR' in vars
. If the right side is nil, it returnsfalse
.?:
- Ternary operator
Standard library
all(list, lambda)
- Returnstrue
if thelambda(element)
is truthy for all elements inlist
. Iterates over the list and invokes thelambda
function on each element. Iflamdbda(element)
ever returns a falsy value (false
or nil), iteration stops immediately andfalse
is returned. Otherwise,true
is returned.lambda
is expressed as<var> -> <expression>
, for examplei -> i > 0
orheader -> header == 'application/json'
.any(list, lambda)
- Returnstrue
if thelambda(element)
is truthy for at least one element inlist
. Iterates over the list and invokes thelambda
function on each element. When an invocation returns a truthy value (neitherfalse
nor nil) iteration stops immediately andtrue
is returned. In all other casesfalse
is returned.lambda
is expressed as<var> -> <expression>
, for examplei -> i > 0
orheader -> header == 'application/json'
.starts_with(string, prefix)
- Returnstrue
if the givenstring
starts with the givenprefix
. Ifprefix
is nil, it returnstrue
; and ifstring
is nil it returnsfalse
unlessprefix
is nil.ends_with(string, suffix)
- Returnstrue
if the givenstring
ends with the givensuffix
.Ifsuffix
is nil, it returnstrue
; and ifstring
is nil it returnsfalse
unlesssuffix
is nil.length(value)
- Returns the length of the givenvalue
. In case of strings, it returns the length of the string. In case of lists, it returns the length of the list. In case of nil values, it returns0
.lowercase(string)
- Converts all characters in the given string to lowercase. Ifstring
is nil, it returns nil.uppercase(string)
- Converts all characters in the given string to uppercase. Ifstring
is nil, it returns nil.substring(string, start)
- Returns a substring of the givenstring
from the given offsetstart
to the end of the string. If thestring
is nil, it returns nil.substring(string, start, length)
- Returns a substring of the givenstring
starting at the offsetstart
, and of the givenlength
. If thestring
is nil, it returns nil.to_boolean(value)
- Converts the givenvalue
into a boolean.false
,'false'
,''
,0
, and nil values returnfalse
, otherwisetrue
.to_integer(value)
- Converts the givenvalue
into a integer. Any non-numeric value is converted to0
.to_float(value)
- Converts the givenvalue
into a float. Any non-numeric value is converted to0
.to_string(value)
- Converts the givenvalue
into a string. Nil values return empty strings.uuidv4()
-> Generates an UUID V4 string.
Embedded expressions
Embedded expressions are expressions that are interpolated into a template string. They are delimited by ${{ expression }}
.
For example, having a BASE_URL
variable defined at project level (dashboard) with the value mywebsite.com
:
https://${{ vars.BASE_URL }}/api/v1
# => https://mywebsite.com/api/v1
If the result is not a string, the result is coerced to a string (see to_string(value)
).
Middleware expressions
Middleware expressions are the following:
force_https
- Redirects to HTTPS ifforce_trailing_slash
- Redirects to the request path ending with trailing slash if the request path does not end with a slashforce_non_trailing_slash
- Redirects to the request path without the trailing slash if the request path ends with a slashhttp_basic_auth(username, password)
- Performs HTTP Basic Auth.
Contexts
Global Context
vars
-map[string]
- variables configured via the dashboard (example:vars.MY_VAR
)secrets
-map[string]
- secret variables configured via the dashboard (example:secrets.MY_SECRET
)build.repository
-string
- The repository expressed asgit:<provider>:<repository full name>
(example:git:github:acme/docs
)build.codeline
-string
- The branch/tag of the commit (example:refs/heads/main
or/refs/tags/v1.0
)build.commit
-string
- The commit SHA of the build.build.commit_author
-string
- The commit author (example:John Doe <john@doe.com>
)build.commit_message
-string
- The commit messageenvironment.id
-uuid
- The Environment identifiedenvironment.name
-string
- The Environment nameenvironment.codeline
-string
- The branch/tag configured in the environment (example:refs/heads/main
or/refs/tags/v1.0
)environment.primary
-boolean
- Set totrue
if the environment is the primary oneproject.id
-uuid
- The Project identifierproject.name
-string
- The Project nameproject.repository
-string
- The repository associated to the project expressed asgit:<provider>:<repository full name>
(example:git:github:acme/docs
)organization.id
-uuid
- The Organization identifierorganization.slug
-string
- The Organization slug
Deployment pipeline Context
build.id
-uuid
- The Build identifierpipeline.id
-uuid
- The Pipeline identifierpipeline.number
-integer
- The Pipeline number
Request context
preview
-boolean
- Set totrue
in case of deployment previewsrequest.scheme
-string
- The scheme of the request:http
orhttps
request.method
-string
- The method of the request (example:GET
)request.host
-string
- The host of the request (example:docs.supranode.com
)request.path
-string
- The request path (example:/blog/request-context
)request.query_string
-string
- The request query string (example:a=1&b=hello
)request.headers
-map[list[string]]
- The request headers
Default build environment variables
CI
- Set to1
SUPRANODE
- Set to1
SUPRANODE_BUILD_CODELINE
SUPRANODE_BUILD_COMMIT
SUPRANODE_BUILD_COMMIT_AUTHOR
SUPRANODE_BUILD_COMMIT_MESSAGE
SUPRANODE_BUILD_ID
SUPRANODE_BUILD_REPOSITORY
SUPRANODE_ENVIRONMENT_CODELINE
SUPRANODE_ENVIRONMENT_ID
SUPRANODE_ENVIRONMENT_NAME
SUPRANODE_ORGANIZATION_ID
SUPRANODE_ORGANIZATION_SLUG
SUPRANODE_PIPELINE_ID
SUPRANODE_PIPELINE_NUMBER
SUPRANODE_PROJECT_ID
SUPRANODE_PROJECT_NAME
SUPRANODE_PROJECT_REPOSITORY