Using Locally with Azure DevOps

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 Azure DevOps

Locally can be used in Azure Pipelines to test your changes in pull requests. We recommend using the Locally extension for Azure DevOps, which adds five tasks to your pipelines:

Locally authenticates using the OIDC token that Azure DevOps issues for a service connection, so you don't need to store any secrets in your pipeline. To set this up:

  1. Install the Locally extension into your Azure DevOps Organisation.
  2. Create (or pick) an Azure Resource Manager service connection that uses Workload Identity Federation, under Project settings -> Service connections, and give your pipeline permission to use it. Locally never uses it to talk to Azure - Azure DevOps only uses it to issue the token.
  3. Add an OIDC Trust for that service connection in your Locally Account.
  4. Pass the service connection to the task using the serviceConnection input, and your Team's UUID using the teamUUID input (or userUUID, if your OIDC Trust belongs to your User).

Heads up

We'd recommend creating a service connection that's only used for Locally, whose identity has no role assignments in Azure - since the token that Azure DevOps issues is the same one that Microsoft Entra accepts to sign in as that identity. As such, rather than reusing a service connection which can deploy to your Azure subscriptions, create a separate one - and if the form grants it a role on a Subscription or Resource Group, remove that role assignment afterwards.

Adding an OIDC Trust

An OIDC Trust tells Locally which service connection 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 Azure DevOps.
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 service connection.
  2. In Azure DevOps, open Project settings -> Service connections, then the service connection, and copy its Issuer and Subject identifier into the matching fields.
  3. Click Add Trust.
Screenshot of the Add Azure DevOps OIDC Trust dialog in the Locally Account, with fields for the Name, Issuer and Subject identifier

Note

Each service connection has its own Subject identifier, so an OIDC Trust allows exactly one service connection. To use another, add another trust.

The User ID or Team ID shown at the top of the page is what you pass to the task as userUUID or teamUUID. Each trust also has a Copy config button, which copies an example configuration you can paste into your pipeline.

Example Pipeline

trigger: none

pr:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  # This example doesn't use anything from the repository,
  # which Azure Pipelines checks out for you by default.

  - task: SetupLocally@1
    displayName: Set up Locally
    inputs:
      # Azure DevOps issues the OIDC token that Locally
      # signs in with for this service connection.
      serviceConnection: my-service-connection
      teamUUID: $(LOCALLY_TEAM_UUID)
      # Installs the recommended plugins by default,
      # which include Microsoft.Storage.

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

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

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

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

  - task: TeardownLocally@1
    displayName: Tear down Locally
    condition: always()

Task: Setting up Locally

The SetupLocally@1 task 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).

- task: SetupLocally@1
  inputs:
    # Azure DevOps issues the OIDC token that Locally
    # signs in with for this service connection.
    serviceConnection: my-service-connection
    teamUUID: $(LOCALLY_TEAM_UUID)
InputDefaultWhat it does
authenticationserviceConnectionHow Locally signs in: serviceConnection (OIDC) or ciKey.
serviceConnectionThe name (or ID) of the service connection to sign in with, which is required unless you're using a CI Key. This has to be known when the pipeline's compiled - as such a literal value or a ${{ parameters.x }} works, but a $(variable) doesn't.
teamUUID / userUUIDThe Team or User that the OIDC Trust belongs to. Set exactly one with a service connection, and neither with a CI Key.
ciKeyA CI Key, passed in from a secret variable.
versionlatestThe version of the Locally CLI to install, such as v2026.11.
pluginsrecommendedThe plugin set to install: none, recommended, all or custom (see Installing Plugins).
pluginsListThe plugins to install with plugins: custom, one per line or comma-separated.
starttrueSet to false to install the CLI without starting Locally.
configureDNStruePoints the agent's DNS at Locally, so that *.locally addresses resolve. Needs passwordless sudo on Linux and macOS agents.
containerRuntimeautoThe container runtime Locally uses: auto, docker or podman.
acceptSqlServerLicencefalseSet to true to accept the Microsoft SQL Server licence.
expectedChecksumA SHA-256 to verify the CLI download against, instead of the published checksum.

Using a CI Key

Azure DevOps Server can't issue OIDC tokens, and a service connection isn't always an option. For those, the task can sign in with a CI Key instead. Store it as a secret variable in your pipeline, and pass it in:

- task: SetupLocally@1
  inputs:
    authentication: ciKey
    # A secret variable in the pipeline (or a variable group).
    ciKey: $(LOCALLY_CI_KEY)

Heads up

A CI Key is a long-lived secret, so use a service connection wherever you can.

Caching plugins

Azure Pipelines tasks can't cache anything themselves, so to avoid downloading plugins on every run, add the Cache@2 task before SetupLocally, with the Locally version and plugin set in the key:

- task: Cache@2
  inputs:
    key: 'locally-plugins | "$(Agent.OS)" | "$(Agent.OSArchitecture)" | v2026.11 | recommended'
    path: $(Agent.TempDirectory)/locally-plugins

- task: SetupLocally@1
  inputs:
    serviceConnection: my-service-connection
    teamUUID: $(LOCALLY_TEAM_UUID)
    version: v2026.11

Task: Installing Plugins

The InstallLocallyPlugins@1 task installs plugins once Locally's already running (reusing the sign-in from SetupLocally) - which is useful when a later part of the job needs plugins that the earlier steps didn't. To install the recommended set of plugins:

- task: InstallLocallyPlugins@1
  inputs:
    plugins: recommended

Or to install every available plugin:

- task: InstallLocallyPlugins@1
  inputs:
    plugins: all

Alternatively you can install a specific list of plugins using plugins: custom, which'll be quicker than installing everything:

- task: InstallLocallyPlugins@1
  inputs:
    plugins: custom
    pluginsList: |
      Microsoft.KeyVault
      Microsoft.ServiceBus
      Microsoft.Storage

The SetupLocally task takes the same plugins and pluginsList inputs - so if you know up-front which plugins the whole job needs, you can specify them there rather than using this task:

- task: SetupLocally@1
  inputs:
    serviceConnection: my-service-connection
    teamUUID: $(LOCALLY_TEAM_UUID)
    plugins: custom
    pluginsList: |
      Microsoft.ServiceBus
      Microsoft.Storage
InputDefaultWhat it does
pluginsnoneThe plugin set to install: none, recommended, all or custom. Whilst SetupLocally defaults to recommended, this task won't install anything unless this is set.
pluginsListThe plugins to install with plugins: custom, one per line or comma-separated.
acceptSqlServerLicencefalseSet to true to accept the Microsoft SQL Server licence, if SetupLocally didn't.
authenticationinheritReuses the sign-in from SetupLocally. Only set serviceConnection or ciKey (with the matching inputs from that task) if it ran with start: false.

Task: Tearing down Locally

The TeardownLocally@1 task should be the last step in any job which uses SetupLocally - it stops Locally, puts the agent's DNS back and (if the job's failed) uploads ci.log as a pipeline artifact for debugging. We'd recommend setting condition: always() so that this runs even when an earlier step fails:

- task: TeardownLocally@1
  displayName: Tear down Locally
  condition: always()

Note

This is particularly important on self-hosted agents, since otherwise the agent's left routing *.locally to Locally's DNS port after Locally's been stopped.
InputDefaultWhat it does
uploadLogsOnFailuretrueUploads ci.log when the job has failed, as an artifact named locally-ci-log-<job name>-<job attempt>.

Task: Saving a Snapshot

The SaveLocallySnapshot@1 task 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 pipeline or someone on your team. This needs to run after SetupLocally, since it reuses its sign-in.

- task: SaveLocallySnapshot@1
  inputs:
    name: before

By default the snapshot's only saved on the agent - as such to use it outside of this job you can upload it as a pipeline artifact, like so:

- task: SaveLocallySnapshot@1
  inputs:
    name: deployed
    description: The staging environment, after terraform apply
    upload: artifact
    # A secret variable in the pipeline (or a variable group).
    passphrase: $(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 pipeline 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 variable.
uploadnoneWhere the snapshot goes once it's saved: none keeps it on the agent, artifact uploads a pipeline artifact, and team shares it with your Locally Team, which needs the Team plan. artifact, team does both.
artifactNamelocally-snapshot-<name>The artifact's name. Artifact names are unique within a run, so give each job's snapshot a different one.
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.

To use the snapshotName, snapshotPath and artifactName output variables in later steps you'll need to give the step a name - e.g. $(save.snapshotPath).

Task: Loading a Snapshot

The LoadLocallySnapshot@1 task 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:

- task: SaveLocallySnapshot@1
  inputs:
    name: before

- script: locally run terraform apply -auto-approve
  displayName: Terraform Apply against Locally

# Puts Locally back as it was before the apply.
- task: LoadLocallySnapshot@1
  inputs:
    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 pipeline has uploaded as an artifact, you'll first need to download it using DownloadPipelineArtifact@2 - and then pass the folder that it's been downloaded to as snapshot:

- task: DownloadPipelineArtifact@2
  inputs:
    buildType: specific
    project: $(System.TeamProject)
    definition: <pipeline ID>
    buildVersionToDownload: latestFromBranch
    branchName: refs/heads/main
    artifactName: locally-snapshot-deployed
    targetPath: $(Pipeline.Workspace)/locally-snapshot

- task: LoadLocallySnapshot@1
  inputs:
    # The folder holding the downloaded .locallysnap file.
    snapshot: $(Pipeline.Workspace)/locally-snapshot
    passphrase: $(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:

- task: LoadLocallySnapshot@1
  inputs:
    snapshot: shared-baseline
    source: team
    passphrase: $(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 agent) 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 variable.
timeoutHow long to wait for running operations to finish, such as 5m. Waits until they're done by default.

How it works

When the SetupLocally task runs, it:

  • Downloads and verifies the Locally CLI (against either an explicit expectedChecksum or the published archive checksum), and adds it to the PATH.
  • Generates short-lived TLS material and sets the LOCALLY_TLS_* and LOCALLY_WORKING_DIRECTORY variables for subsequent steps.
  • Requests an OIDC token from Azure DevOps for your service connection. The token is only passed to Locally - it's never set as a pipeline variable.
  • Installs the requested plugin set.
  • Starts locally ci in the background, which exchanges the token with the Locally API against your configured OIDC trust, and waits until the local endpoints are ready.
  • Points the agent's DNS at Locally, so that *.locally addresses (such as Key Vault data planes) resolve. This needs passwordless sudo on Linux and macOS agents, which Microsoft-hosted agents have - on a self-hosted agent without it, set configureDNS: false.

The tasks run on Microsoft-hosted and self-hosted Linux, macOS and Windows agents, on x64 and arm64.

Next steps

The Automation API lets later steps in your job look up Locally's endpoints. Once Locally's running, your pipeline runs commands through locally run as it would on your machine - the Guides cover each tool.

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.