Environments

Environments are a new feature since v2.5.0. They are useful when you want to create multiple RunsOn stacks that are isolated from each other, with different IAM permissions or stack configurations, etc. This allows you to map existing environments and requirements (e.g. production, staging, development) to different RunsOn stacks.

Each environment will also get linked to its own private GitHub App, which means you can enable a different set of repositories for each environment if needed.

How it works

At installation time, you can specify the environment name for your RunsOn stack. By default the environment is named production, and is the one targeted by the workflow if no env label is specified.

Then, in your workflow, you can specify the environment name with the env label.

Example

Assuming you have created a RunsOn stack with the Environment parameter set to staging, you can target it with the following workflow definition:

jobs:
  build:
    runs-on:
      - runs-on=${{ github.run_id }}
      - runner=2cpu-linux-x64
      - env=staging
      - ...other labels...

All other RunsOn stacks will ignore this workflow.

Considerations

Caution

With GitHub, runners will pick jobs as long as their labels match a subset of the runner labels. So if you are using this feature, make sure that all your workflows explicitly define the env label. Otherwise, runners might be assigned to workflows that they shouldn’t.

For instance, if workflow A has labels [runs-on, runner=2cpu-linux-x64, env=staging] and workflow B has labels [runs-on, runner=2cpu-linux-x64] (env=production is inferred), workflow B might steal the runner from workflow A because its labels are a subset of workflow A. You can circumvent this issue by using the run-id label for better uniqueness (although it’s still shared among jobs within the same workflow), but it is recommended to also set workflow B labels to [runs-on, runner=2cpu-linux-x64, env=production] to avoid any issues.

Each RunsOn stack incurs a cost (AWS costs + regularly upgrading the stack), and we recommend that you create as few as possible. The majority of clients only create one stack.