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:
setup-locally- installs and starts Locally.install-plugins- installs plugins later in a job.teardown- stops Locally at the end of a job.snapshot-save- saves everything in Locally as a snapshot.snapshot-load- replaces everything in Locally with a snapshot.snapshot-diff- shows what changed between two snapshots, in the job summary and on the pull request.
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:
- Add an OIDC Trust for your repository in your Locally Account.
- Add
permissions: id-token: writeto your workflow, so GitHub can issue OIDC tokens. - Pass your Team's UUID to the action using the
team-uuidinput (oruser-uuid, if your OIDC Trust belongs to your User).
Note
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:
- In your Locally Account, open Account -> Personal CI (OIDC) for yourself, or Teams -> [name] -> Team CI (OIDC) for a Team.
- Click Add Trust, then choose GitHub Actions.
- Give the trust a Name, such as the name of the repository.
- 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). - Choose whether to allow Only this repository, or Every repository owned by this organisation or user.
- Optionally, enter a Branch to only allow workflows running on that branch - otherwise any branch can sign in.
- Click Add Trust.
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
| Input | Default | What it does |
|---|---|---|
| team-uuid / user-uuid | The Team or User that the OIDC Trust belongs to. Set exactly one. | |
| version | latest | The version of the Locally CLI to install, such as v2026.11. |
| plugins | recommended | The plugin set to install: none, recommended, all or custom. |
| plugins-list | The plugins to install with plugins: custom, one per line or comma-separated. | |
| start | true | Set to false to install the CLI without starting Locally. |
| configure-dns | true | Points the runner's DNS at Locally, so that *.locally addresses resolve. Needs passwordless sudo on Linux and macOS runners. |
| accept-sql-server-licence | false | Set to true to accept the Microsoft SQL Server licence. |
| cache | true | Caches the plugin directory between runs. |
| cache-key-prefix | A prefix for the cache key, to start from a fresh cache or keep one per branch. | |
| expected-checksum | A 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
| Input | Default | What it does |
|---|---|---|
| plugins | none | The 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-list | The plugins to install with plugins: custom, one per line or comma-separated. | |
| team-uuid / user-uuid | Only needed if setup-locally didn't set them - otherwise they're reused. | |
| accept-sql-server-licence | false | Set 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
*.locally to Locally's DNS port after Locally's been stopped.| Input | Default | What it does |
|---|---|---|
| upload-logs-on-failure | true | Uploads 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
passphrase before uploading or sharing one.| Input | Default | What it does |
|---|---|---|
| name | Required. The name to save the snapshot under: letters, digits, ., _ and -. | |
| description | One line on what the snapshot holds and why it was taken. | |
| passphrase | Encrypts the snapshot with this passphrase, passed in from a secret. | |
| upload | none | Where 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-name | locally-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-days | How many days to keep the artifact for. Uses the repository's setting by default. | |
| artifact-overwrite | false | Replaces an artifact of the same name from earlier in this run. |
| team | The Locally Team to share with. Only needed if you're in more than one. | |
| timeout | How 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 }}
| Input | Default | What it does |
|---|---|---|
| snapshot | Required. 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. | |
| source | local | Where the snapshot comes from: local (on the runner) or team. |
| team | The Locally Team to load from. Only needed if you're in more than one. | |
| passphrase | The snapshot's passphrase, if it's encrypted, passed in from a secret. | |
| timeout | How 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.
| Input | Default | What it does |
|---|---|---|
| from | Required. The earlier side of the comparison. | |
| from-source | local | Where from comes from: local, artifact or team. |
| from-run-id / from-branch | With artifact, the run that uploaded it, or a branch to use the most recent one from. This run by default. | |
| to | The later side of the comparison. Compares against what's in Locally now by default. | |
| to-source / to-run-id / to-branch | As for from. | |
| team | The Locally Team, for a team source. Only needed if you're in more than one. | |
| passphrase | The passphrase for encrypted snapshots (both sides need the same one). | |
| all | false | Also compares timestamps, etags, the activity log, delivered events and issued tokens. |
| comment | false | Comments on the pull request, which needs pull-requests: write. |
| comment-key | default | Which comment to update, so that several diffs can each have their own. |
| fail-on-changes | false | Fails 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-checksumor the published archive checksum). - Generates short-lived TLS material and exports the
LOCALLY_TLS_*andLOCALLY_WORKING_DIRECTORYenvironment variables for subsequent steps. - Installs the requested plugin set (cached between runs by default).
- Starts
locally ciin 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. Iflocally ciexits during startup, the step fails straight away and shows its log. - Points the runner's DNS at Locally, so that
*.locallyaddresses (such as Key Vault data planes) resolve. This needs passwordlesssudoon Linux and macOS runners, which GitHub-hosted runners have - on a self-hosted runner without it, setconfigure-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.
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in