During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Using Locally in CI
You can use Locally in your CI pipeline to test and validate your infrastructure and application changes in pull requests.
In CI, Locally authenticates using Workload Identity Federation (OIDC), or a CI Key where your CI system can't issue OIDC tokens - so you control which of your repositories can run Locally, and when your OIDC Trust belongs to a Team, Locally uses the same Locally Runbooks as the rest of your team.
There are dedicated guides for each CI provider:
- GitHub Actions - using the
locallybuild/setup-locallyaction. - GitLab CI.
- Azure DevOps - using the Locally extension's
SetupLocallytask. - Other CI Tools - configuring Locally manually, for any other CI provider.
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 Workload Identity Federation (OIDC)
With Workload Identity Federation, 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, GitLab and Azure DevOps, but it's possible to configure Locally to work with any OIDC provider (and if you do, we'd love to hear about it!).
Note
You can configure OIDC within your Locally Account, either for yourself (Account -> Personal CI (OIDC)) or for your Team (Teams -> [name] -> Team CI (OIDC)). When you add a New OIDC Trust, you'll need to specify:
- GitHub: The Subject prefix of the repository (from its Settings -> Actions -> OIDC page), whether to allow only that repository or every repository owned by the same organisation or user, and optionally a branch (see the GitHub Actions guide).
- GitLab: The Username of the GitLab User/Group where you want to launch Locally in GitLab CI.
- Azure DevOps: The Issuer and Subject identifier of the service connection that Locally signs in with (see the Azure DevOps guide).
- GitLab: 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). - GitLab: The Name of the Branch where you want to run Locally (you can also use
*to run against all branches).
Locally signs in with the first of these it finds:
- Custom OIDC providers -
LOCALLY_OIDC_TOKENorLOCALLY_OIDC_TOKEN_FILE, containing a pre-obtained OIDC token. - CI Keys -
LOCALLY_CI_KEYorLOCALLY_CI_KEY_FILE, for CI systems that can't issue OIDC tokens (see CI Keys). - GitHub Actions - detected automatically, but requires
permissions: id-token: writein your workflow. - GitLab CI - requires an
id_tokensconfiguration in your job with aLOCALLY_ID_TOKENvariable.
In Azure DevOps, the SetupLocally task requests the token for your service connection and hands it to Locally as LOCALLY_OIDC_TOKEN.
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 or Azure DevOps 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.
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in