Using Locally in CI

How CI mode differs

Running Locally in CI is almost the same as running it on your machine with locally build, with a few differences:

• CI mode is configured using Environment Variables, rather than locally setup.
• CI mode doesn't include the Locally Dashboard, since this is primarily a development aid.
• CI mode doesn't log requests/responses.
• CI mode includes a dedicated set of endpoints for automation purposes.

Setting up an OIDC Trust

Locally signs in from CI using an OIDC (OpenID Connect) token from your CI provider, so you don't need to store any long-lived credentials in your CI configuration. There's built-in support for GitHub and GitLab, but it's possible to configure Locally to work with any OIDC provider (and if you do, we'd love to hear about it!).

You can configure OIDC within your Locally Account, either against your User (Account -> User CI (OIDC)) or against your Team (Teams -> [name] -> Team CI (OIDC)). When you add a New OIDC Trust, you'll need to specify:

• GitHub: The Username of the GitHub User/Organisation where you want to launch Locally in GitHub Actions.
• GitLab: The Username of the GitLab User/Group where you want to launch Locally in GitLab CI.
• All: The Name of the Repository where you want to run Locally (you can also use * to allow working against all repositories within this User/Organisation).
• All: The Name of the Branch where you want to run Locally (you can also use * to run against all branches).

Locally looks for an OIDC token in the following order:

1. Custom OIDC providers - LOCALLY_OIDC_TOKEN or LOCALLY_OIDC_TOKEN_FILE, containing a pre-obtained OIDC token.
2. GitHub Actions - detected automatically, but requires permissions: id-token: write in your workflow.
3. GitLab CI - requires an id_tokens configuration in your job with a LOCALLY_ID_TOKEN variable.

Plan Limits

How long a CI session can run, and how many can run at once, depends on your plan:

• Starter - sessions of up to 4 hours, and 1 concurrent CI instance.
• Standard - unlimited session length, and 3 concurrent CI instances.
• Team - unlimited session length, and unlimited CI instances.

When a session reaches its limit, Locally exits with exit code 2 - so you can tell a session timing out apart from other failures in your CI pipeline:

• Exit code 0 - Locally exited normally.
• Exit code 1 - An error occurred.
• Exit code 2 - The session limit was reached (Starter plan).

Requirements

Locally needs access to the same ports and endpoints as when running on your machine.

Next steps

To set it up, follow the GitHub Actions guide, or Other CI Tools for any other CI provider. Once Locally's running, your pipeline runs commands through locally run as it would on your machine - the Guides cover each tool.