Using Locally with GitHub Actions

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()

Choosing a Plugin Set

By default the action installs the recommended plugin set. To install every available plugin, or just a specific list, use the plugins input:

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

See the action README for the full input reference, including pinning a specific CLI version, controlling the plugin cache, and using the install-plugins subaction to install additional plugins later in a job.

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 .sha256 sibling).
• 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.

The teardown subaction stops locally ci at the end of the job and, on failure, uploads ci.log as a workflow artifact for debugging. The if: always() ensures cleanup runs even if earlier steps fail.

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.