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:

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

Standard library

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:

Contexts

Global Context

Deployment pipeline Context

Request context

Default build environment variables