Using Locally in CI

Preview

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:

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

If your CI system can't issue OIDC tokens - such as Bamboo, AWS CodeBuild, or Jenkins without its OpenID Connect plugin - you can use a CI Key instead. Prefer Workload Identity Federation wherever it's available, as a CI Key is a long-lived secret.

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:

  1. Custom OIDC providers - LOCALLY_OIDC_TOKEN or LOCALLY_OIDC_TOKEN_FILE, containing a pre-obtained OIDC token.
  2. CI Keys - LOCALLY_CI_KEY or LOCALLY_CI_KEY_FILE, for CI systems that can't issue OIDC tokens (see CI Keys).
  3. GitHub Actions - detected automatically, but requires permissions: id-token: write in your workflow.
  4. GitLab CI - requires an id_tokens configuration in your job with a LOCALLY_ID_TOKEN variable.

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.

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

A local cloud for you and your AI agents.

Your Azure infrastructure, running on your machine. Deploy in seconds, break things freely, and ship to Azure when you're ready.