Skip to main content

Environments

In Skiff 2 there are two different kinds of environments: Long-lived and ad-hoc environments. They share a lot of similarities, but there are some important differences in setup and use that will be explained.

Skiff 2 will automatically make the services in an environment available at a URL like <ENV_NAME>-<SERVICE_NAME>.<PROJECT_NAME>.apps.allenai.org. For example, a web service in the qa environment of the test-app project will have the URL qa-web.test-app.apps.allenai.org. The URL will also be shown in the GitHub deployment after it deploys for the first time.

main is prod by default

Deploys from the main branch map to the prod environment. The prod environment is special: the root service is served from the bare project domain (e.g. test-app.apps.allenai.org, no env prefix), and only prod can route custom domains. Which branch maps to prod is configurable via prodBranch in skiff2.json, but it is recommended to not change it once set.

Long-lived environments​

You should set up a long-lived environment if you want to have an environment that you'll use for a while. dev or qa branches that are deployed to before deploying to prod are good candidates for long-lived environments.

Long-lived environments have deletion protection applied by default. This ensures that the services in that environment can't be accidentally removed.

To set up a long-lived environment you'll need to make these changes:

  1. Update the environments field in skiff2.json to include your branch

    // skiff2.json
    {
        "environments": ["main", "<GIT_BRANCH_NAME>"],
        ...
    }
    warning

    If you don't have an environments field already, ensure you add "main" to the list with your other environment to ensure your main branch stays as a long-lived environment.

  2. Update your deployment action to include your branch

    If you followed the getting started guide your deployment action will look something like this:

    # deploy.yml
    name: Skiff2 Build & Deploy
    on:
        push:
            branches:
                - main

    Add your branch name to the branches list like this:

    # deploy.yml
    name: Skiff2 Build & Deploy
    on:
        push:
            branches:
                - main
                - <GIT_BRANCH_NAME>

Ad hoc environments​

You should use an ad hoc environment for things that you want to set up and tear down quickly. In-development branches, UI testing, and other quick demos are good candidates for ad hoc environments.

Ad hoc environments don't have deletion protection applied by default.

Secrets and environment variables

Secrets are scoped by environment name (<ENV_NAME>-<SERVICE_NAME>-<ENV_VARIABLE_NAME>), so a prod--prefixed secret will not be available in your ad hoc environment. Before deploying, either:

  • Create copies of the secrets prefixed with your ad hoc environment's name (e.g. my-branch-api-API_KEY), or
  • Use the global- prefix (e.g. global-api-API_KEY) so the same secret is applied across all environments, including ad hoc ones.

To set up an ad hoc environment you need to change the deployment action on that branch. If you followed the getting started guide your deployment action will look something like this:

# deploy.yml
name: Skiff2 Build & Deploy
on:
    push:
        branches:
            - main

Add your branch name to the branches list like this:

# deploy.yml
name: Skiff2 Build & Deploy
on:
    push:
        branches:
            - main
            - <GIT_BRANCH_NAME>
Clean up when you're done

Ad hoc environments are not torn down automatically. When you're finished with one, you need to manually delete the apps it created so they don't keep consuming resources.