Using Locally with GitHub Actions

Preview

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

Using Locally with GitHub Actions

You can run Locally in GitHub Actions to test your changes in pull requests - and we provide actions in the locallybuild/setup-locally repository to make setup easy. These actions are:

Locally authenticates using GitHub's built-in OIDC tokens, so you don't need to store any secrets in your repository. To set this up:

  1. Add an OIDC Trust for your repository in your Locally Account.
  2. Add permissions: id-token: write to your workflow, so GitHub can issue OIDC tokens.
  3. Pass your Team's UUID to the action using the team-uuid input (or user-uuid, if your OIDC Trust belongs to your User).

Note

If you can't use OIDC for some reason, Locally can also sign in with a CI Key - although the setup-locally actions only support OIDC, so you'd need to run locally ci yourself. We'd strongly recommend using OIDC wherever possible, since a CI Key is a long-lived secret which you'll need to store and rotate.

Adding an OIDC Trust

An OIDC Trust tells Locally which GitHub repositories can sign in. It can belong to your User, or to a Team - in which case Locally uses your Team's Runbooks too. To add one:

  1. In your Locally Account, open Account -> Personal CI (OIDC) for yourself, or Teams -> [name] -> Team CI (OIDC) for a Team.
  2. Click Add Trust, then choose GitHub Actions.
Screenshot of the Add OIDC Trust dialog in the Locally Account, offering GitHub Actions, GitLab CI, Azure DevOps and Custom
  1. Give the trust a Name, such as the name of the repository.
  2. Paste in the Subject prefix, which you'll find in the repository on GitHub under Settings -> Actions -> OIDC (https://github.com/{owner}/{repository}/settings/actions/oidc-configuration).
  3. Choose whether to allow Only this repository, or Every repository owned by this organisation or user.
  4. Optionally, enter a Branch to only allow workflows running on that branch - otherwise any branch can sign in.
  5. Click Add Trust.
Screenshot of the Add GitHub OIDC Trust dialog in the Locally Account, with fields for the Name, Subject prefix, which repositories to allow and an optional Branch

The User ID or Team ID shown at the top of the page is what you pass to the action as user-uuid or team-uuid. The examples on this page read it from a repository variable named LOCALLY_TEAM_UUID - it isn't a secret, so a variable works fine. Each trust also has a Copy config button, which copies an example configuration you can paste into your workflow.

Example Workflow

name: Locally

on:
  pull_request:
    types: ['opened', 'synchronize']

jobs:
  provision:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      # Required: GitHub mints the OIDC token
      # that Locally signs in with.
      id-token: write
    steps:
      # This example doesn't use anything from the
      # repository, but if you're copying it and want
      # to use files from your repository (for example,
      # to run your tests), check it out first:
      #
      # - uses: actions/checkout@v7

      - name: Set up Locally (with Microsoft.Storage)
        uses: locallybuild/setup-locally@v1
        with:
          team-uuid: ${{ vars.LOCALLY_TEAM_UUID }}
          plugins: custom
          plugins-list: |
            Microsoft.Storage

      - name: Create a Resource Group using the Azure CLI
        run: locally run az group create -n example -l berlin

      - name: List the Resource Groups using the Azure CLI
        run: locally run az group list

      - name: Create a Storage Account using the Azure CLI
        run: |
          locally run az storage account create \
            -n account1 -g example -l berlin --sku Standard_LRS

      - name: Create a Container within that Storage Account
        run: |
          locally storage container create \
            --account account1 --name mydata

      - name: Tear down Locally
        uses: locallybuild/setup-locally/teardown@v1
        if: always()

Action: Setting up Locally

The locallybuild/setup-locally@v1 action installs the Locally CLI and the recommended plugins, signs in and then starts Locally - as such it needs to run before any step which uses locally run (see How it works below). To install a specific list of plugins instead, use plugins: custom:

- uses: locallybuild/setup-locally@v1
  with:
    team-uuid: ${{ vars.LOCALLY_TEAM_UUID }}
    plugins: custom
    plugins-list: |
      Microsoft.ServiceBus
      Microsoft.Storage
InputDefaultWhat it does
team-uuid / user-uuidThe Team or User that the OIDC Trust belongs to. Set exactly one.
versionlatestThe version of the Locally CLI to install, such as v2026.11.
pluginsrecommendedThe plugin set to install: none, recommended, all or custom.
plugins-listThe plugins to install with plugins: custom, one per line or comma-separated.
starttrueSet to false to install the CLI without starting Locally.
configure-dnstruePoints the runner's DNS at Locally, so that *.locally addresses resolve. Needs passwordless sudo on Linux and macOS runners.
accept-sql-server-licencefalseSet to true to accept the Microsoft SQL Server licence.
cachetrueCaches the plugin directory between runs.
cache-key-prefixA prefix for the cache key, to start from a fresh cache or keep one per branch.
expected-checksumA SHA-256 to verify the CLI download against, instead of the published checksum.

Action: Installing Plugins

The locallybuild/setup-locally/install-plugins@v1 action installs plugins later in a job (reusing the sign-in from setup-locally) - which is useful when a later part of the job needs plugins that the earlier steps didn't:

- uses: locallybuild/setup-locally@v1
  with:
    team-uuid: ${{ vars.LOCALLY_TEAM_UUID }}
    plugins: none

# ...

- uses: locallybuild/setup-locally/install-plugins@v1
  with:
    plugins: custom
    plugins-list: |
      Microsoft.ServiceBus
      Microsoft.Storage
InputDefaultWhat it does
pluginsnoneThe plugin set to install: none, recommended, all or custom. Whilst setup-locally defaults to recommended, this action won't install anything unless this is set.
plugins-listThe plugins to install with plugins: custom, one per line or comma-separated.
team-uuid / user-uuidOnly needed if setup-locally didn't set them - otherwise they're reused.
accept-sql-server-licencefalseSet to true to accept the Microsoft SQL Server licence, if setup-locally didn't.

Action: Tearing down Locally

The locallybuild/setup-locally/teardown@v1 action should be the last step in any job which uses setup-locally - it stops Locally, puts the runner's DNS back and (if the job's failed) uploads ci.log as a workflow artifact for debugging. We'd recommend setting if: always() so that this runs even when an earlier step fails:

- uses: locallybuild/setup-locally/teardown@v1
  if: always()

Note

This is particularly important on self-hosted runners, since otherwise the runner's left routing *.locally to Locally's DNS port after Locally's been stopped.
InputDefaultWhat it does
upload-logs-on-failuretrueUploads ci.log when the job has failed, as an artifact named locally-ci-log-<job id> (with the matrix index appended for each leg of a matrix job).

Action: Saving a Snapshot

The locallybuild/setup-locally/snapshot-save@v1 action saves all of the resources and data in Locally as a Locally Snapshot (which requires the Standard plan or above) - which can be used as a checkpoint to go back to later in the job, or to hand a deployed environment to another workflow or someone on your team. This needs to run after setup-locally, since it reuses its sign-in.

By default the snapshot's only saved on the runner - to use it outside of this job, we'd recommend pushing it to Locally Snapshots (using upload: team, on the Team plan) or uploading it as a workflow artifact:

- uses: locallybuild/setup-locally/snapshot-save@v1
  with:
    name: deployed
    upload: artifact
    passphrase: ${{ secrets.LOCALLY_SNAPSHOT_PASSPHRASE }}

Heads up

Snapshots contain the credentials for your resources (such as Key Vault secrets and access keys) and anyone who can download a workflow artifact can read an unencrypted snapshot - as such we'd recommend setting passphrase before uploading or sharing one.
InputDefaultWhat it does
nameRequired. The name to save the snapshot under: letters, digits, ., _ and -.
descriptionOne line on what the snapshot holds and why it was taken.
passphraseEncrypts the snapshot with this passphrase, passed in from a secret.
uploadnoneWhere the snapshot goes once it's saved: none keeps it on the runner, artifact uploads a workflow artifact, and team shares it with your Locally Team, which needs the Team plan. artifact, team does both.
artifact-namelocally-snapshot-<name>-<job id>The artifact's name, with the matrix index appended for each leg of a matrix job. If you set this in a matrix job, include the matrix values in it.
artifact-retention-daysHow many days to keep the artifact for. Uses the repository's setting by default.
artifact-overwritefalseReplaces an artifact of the same name from earlier in this run.
teamThe Locally Team to share with. Only needed if you're in more than one.
timeoutHow long to wait for running operations to finish, such as 5m. Waits until they're done by default.

The name, path, artifact-name, artifact-id and artifact-url outputs can be used in later steps and jobs - use artifact-name to pass the snapshot to a later job, rather than working the name out.

Action: Loading a Snapshot

The locallybuild/setup-locally/snapshot-load@v1 action replaces everything in Locally with a snapshot - which is useful for starting a job from an environment that's already been deployed, or for putting Locally back as it was between two sets of tests, like so:

- uses: locallybuild/setup-locally/snapshot-save@v1
  with:
    name: before

- run: npm test

- uses: locallybuild/setup-locally/snapshot-load@v1
  with:
    snapshot: before

Any plugins which the snapshot needs (and aren't already installed) are installed first - and if the snapshot can't be loaded in full, then Locally's left as it was.

To load a snapshot which another workflow (or an earlier run) has uploaded as an artifact, you'll first need to download it using actions/download-artifact - and then pass the folder that it's been downloaded to as snapshot:

- uses: actions/download-artifact@v8
  with:
    name: locally-snapshot-deployed
    path: ${{ runner.temp }}/locally-snapshot
    # for an artifact from another run:
    # run-id: ...
    # github-token: ${{ github.token }}

- uses: locallybuild/setup-locally/snapshot-load@v1
  with:
    snapshot: ${{ runner.temp }}/locally-snapshot
    passphrase: ${{ secrets.LOCALLY_SNAPSHOT_PASSPHRASE }}

If you're on the Team plan, you can also load a snapshot that's been shared with your Locally Team using source: team:

- uses: locallybuild/setup-locally/snapshot-load@v1
  with:
    snapshot: shared-baseline
    source: team
    passphrase: ${{ secrets.LOCALLY_SNAPSHOT_PASSPHRASE }}
InputDefaultWhat it does
snapshotRequired. With source: local, a snapshot's name, the path of a .locallysnap file, or a folder holding exactly one. With source: team, the name of a shared snapshot.
sourcelocalWhere the snapshot comes from: local (on the runner) or team.
teamThe Locally Team to load from. Only needed if you're in more than one.
passphraseThe snapshot's passphrase, if it's encrypted, passed in from a secret.
timeoutHow long to wait for running operations to finish, such as 5m. Waits until they're done by default.

Action: Comparing Snapshots

The locallybuild/setup-locally/snapshot-diff@v1 action shows what changed between two snapshots, or between a snapshot and what's in Locally now - in the job summary and (optionally) as a comment on the pull request, which is updated in place on later runs. Locally needs to be running for this, even when comparing two snapshots.

To see what a pull request changes, take a snapshot before deploying and then compare it with what's in Locally afterwards:

permissions:
  contents: read
  id-token: write      # Locally signs in using GitHub's OIDC token
  pull-requests: write # to comment on the pull request

steps:
  - uses: actions/checkout@v7

  - uses: locallybuild/setup-locally@v1
    with:
      team-uuid: ${{ vars.LOCALLY_TEAM_UUID }}

  - uses: locallybuild/setup-locally/snapshot-save@v1
    with:
      name: before

  - run: terraform apply -auto-approve

  - uses: locallybuild/setup-locally/snapshot-diff@v1
    with:
      from: before
      comment: true

  - uses: locallybuild/setup-locally/teardown@v1
    if: always()

To compare a pull request with main instead, upload a snapshot as an artifact on each push to main:

- uses: locallybuild/setup-locally/snapshot-save@v1
  with:
    name: deployed
    upload: artifact
    artifact-name: locally-snapshot-deployed
    passphrase: ${{ secrets.LOCALLY_SNAPSHOT_PASSPHRASE }}

Then in pull requests, compare the most recent one from main with what the pull request deploys:

permissions:
  contents: read
  actions: read        # to find and download artifacts from other runs
  id-token: write
  pull-requests: write

steps:
  # ... set up Locally and deploy ...

  - uses: locallybuild/setup-locally/snapshot-diff@v1
    with:
      from: locally-snapshot-deployed
      from-source: artifact
      from-branch: main
      passphrase: ${{ secrets.LOCALLY_SNAPSHOT_PASSPHRASE }}
      comment: true

Each side of the comparison can be a snapshot on the runner (local, the default), a workflow artifact from this run, another run or the most recent one on a branch (artifact, which needs actions: read), or one shared with your Locally Team (team). Credentials are never shown - a changed key or secret is reported as changed, without its value.

InputDefaultWhat it does
fromRequired. The earlier side of the comparison.
from-sourcelocalWhere from comes from: local, artifact or team.
from-run-id / from-branchWith artifact, the run that uploaded it, or a branch to use the most recent one from. This run by default.
toThe later side of the comparison. Compares against what's in Locally now by default.
to-source / to-run-id / to-branchAs for from.
teamThe Locally Team, for a team source. Only needed if you're in more than one.
passphraseThe passphrase for encrypted snapshots (both sides need the same one).
allfalseAlso compares timestamps, etags, the activity log, delivered events and issued tokens.
commentfalseComments on the pull request, which needs pull-requests: write.
comment-keydefaultWhich comment to update, so that several diffs can each have their own.
fail-on-changesfalseFails the step when there are differences, after writing the summary and comment.

The has-changes output is true when anything changed, alongside counts of the resources and data added, changed and removed. See the action README for every input and output, including the job summary, artifact and comment settings.

How it works

When the setup-locally action runs, it:

  • Downloads and verifies the Locally CLI (against either an explicit expected-checksum or the published archive checksum).
  • Generates short-lived TLS material and exports the LOCALLY_TLS_* and LOCALLY_WORKING_DIRECTORY environment variables for subsequent steps.
  • Installs the requested plugin set (cached between runs by default).
  • Starts locally ci in the background, which requests an OIDC token from GitHub, exchanges it with the Locally API against your configured OIDC trust, and waits until the local endpoints are ready. If locally ci exits during startup, the step fails straight away and shows its log.
  • Points the runner's DNS at Locally, so that *.locally addresses (such as Key Vault data planes) resolve. This needs passwordless sudo on Linux and macOS runners, which GitHub-hosted runners have - on a self-hosted runner without it, set configure-dns: false.

The actions run on GitHub-hosted and self-hosted Linux, macOS and Windows runners.

Examples

This example repository runs the setup-locally action in a working GitHub Actions workflow you can copy:

Next steps

The Automation API lets later steps in your job look up Locally's endpoints. If you use Claude Code or another agent, the locally-ci skill in the Agent Skills can set up a workflow like this for you.

Should you encounter any issues, please take a look at the troubleshooting section, reach out in our Discord or open an issue and we'll take a look.

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.