ooooo                                      oooo  oooo              
`888'                                      `888  `888              
 888          .ooooo.   .ooooo.   .oooo.    888   888  oooo    ooo 
 888         d88' `88b d88' `\"Y8 `P  )88b   888   888   `88.  .8'
 888         888   888 888        .oP\"888   888   888    `88..8'
 888       o 888   888 888   .o8 d8(  888   888   888     `888'
o888ooooood8 `Y8bod8P' `Y8bod8P' `Y888\"\"8o o888o o888o     .8'
                                                       .o..P'
                                                       `Y8P'

azure-devops-extension

This repository contains the Locally extension for Azure DevOps, which adds several Azure Pipelines tasks for Locally Build:

• SetupLocally@1 - installs and configures Locally.
• InstallLocallyPlugins@1 - allows for installing Locally Plugins.
• TeardownLocally@1 - provides a means of stopping Locally once it's been launched in CI mode.
• SaveLocallySnapshot@1 - takes a Locally Snapshot of everything in Locally, and optionally uploads it as a pipeline artifact and/or shares it with your Locally Team.
• LoadLocallySnapshot@1 - replaces everything in Locally with a snapshot.

These are the Azure Pipelines equivalent of the locallybuild/setup-locally GitHub Actions.

Azure DevOps Services (dev.azure.com) is supported, on Microsoft-hosted and self-hosted Linux, macOS and Windows agents (x64 and arm64). Azure DevOps Server can't issue OIDC tokens, so it can only be used with a CI Key.

Installing the extension

Install the Locally extension from the Visual Studio Marketplace into your Azure DevOps Organisation. Once it's installed, every pipeline in that Organisation can use the tasks above.

OIDC Configuration for a Team/User (obtaining teamUUID or userUUID)

Locally launches via OIDC, which is configured either against your User or against a Team (Locally Account -> Teams -> [Name] -> Team CI (OIDC).

In Azure Pipelines the OIDC token is issued for a service connection, so there are two halves to this: a service connection in Azure DevOps, and a trust for it in Locally.

1. Create (or pick) a service connection in Azure DevOps

Locally needs an Azure Resource Manager service connection that uses Workload Identity Federation. Create one just for Locally, whose identity has no role assignments in Azure (see the warning below), rather than reusing one you deploy with:

1. In your Azure DevOps project, open Project settings -> Service connections.
2. Click New service connection and select Azure Resource Manager.
3. Choose Workload identity federation as the credential, and complete the form.
4. Give the pipeline(s) that will run Locally permission to use the service connection.

Locally never uses this service connection to talk to Azure: Azure DevOps only uses it to issue the token.

[!WARNING] The token Azure DevOps issues for a service connection is the same one Microsoft Entra accepts to sign in as that service connection's identity. Azure DevOps can't issue one for a different audience, so until it expires, anything that holds the token (the locally CLI, and the Locally service it signs in to) could exchange it for access to whatever that identity can reach in Azure.

So use a dedicated service connection whose app registration or managed identity has no role assignments: the token is then only good for proving to Locally which service connection the job used. If the form asks you to grant a role on a subscription or resource group, remove that role assignment afterwards. Don't reuse a service connection that can deploy to your Azure subscriptions.

Once it's created, open the service connection and copy its Issuer and Subject identifier. You'll need both in the next step.

2. Add a trust for it in Locally

If you've not already configured OIDC within Locally, on either the Team CI (OIDC) or User CI (OIDC) page linked above, you can:

1. Click Add Trust in the top-right of the page.
2. Select Azure DevOps.
3. Under Issuer, paste the service connection's Issuer (for example https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0).
4. Under Subject identifier, paste the service connection's Subject identifier (for example /eid1/c/pub/t/.../sc/.../...).

At the end of this flow, you'll see the Team/User UUID to use with the tasks within this repository.

The trust matches the subject exactly, and each service connection has its own, so a trust allows exactly one service connection. To allow another, add another trust.

For reference, these are the claims in the token that Azure DevOps issues:

If the trust doesn't match, locally ci fails and prints the issuer and subject it was given, so you can compare them with the trust.

Example: Using SetupLocally@1

To use Locally against your Team, you can use the following Azure Pipelines configuration:

steps:
  - task: SetupLocally@1
    inputs:
      serviceConnection: my-service-connection # see above
      teamUUID: 'abc123'
      # plugins: recommended  # default; or `none`, `all`, `custom`

To use Locally in CI against your User, you can use the following Azure Pipelines configuration:

steps:
  - task: SetupLocally@1
    inputs:
      serviceConnection: my-service-connection # see above
      userUUID: 'bcd234' # see above
      # plugins: recommended  # default; or `none`, `all`, `custom`

By default, both of these will install the Recommended set of Plugins, but you can specify a custom list to install for example:

steps:
  - task: SetupLocally@1
    inputs:
      serviceConnection: my-service-connection
      teamUUID: $(LOCALLY_TEAM_UUID)
      plugins: custom
      pluginsList: |
        Microsoft.ServiceBus
        Microsoft.Storage

pluginsList accepts one plugin per line (as above) or a comma-separated list (Microsoft.ServiceBus,Microsoft.Storage). The newline form is easier to read and gives cleaner diffs as the list grows.

The full list of arguments:

¹ With a service connection, exactly one of teamUUID or userUUID must be set, depending on whether the OIDC trust is configured at team or user scope. Setting both fails; setting neither fails. With a CI Key neither is needed, since the key says which team or user it belongs to.

See tasks/SetupLocallyV1/task.json for the full input reference.

Example: Using SetupLocally@1 with a CI Key

Where a service connection isn't an option (Azure DevOps Server, for example), you can create a CI Key in your Locally Account, store it as a secret variable in the pipeline, and pass it in:

steps:
  - task: SetupLocally@1
    inputs:
      authentication: ciKey
      ciKey: $(LOCALLY_CI_KEY)

A CI Key is a long-lived secret that you have to store and rotate, so we'd recommend using OIDC where possible.

Using Locally in later steps

Once SetupLocally@1 has run, locally is on the PATH and later steps in the job find the running locally ci without any further configuration. Use locally run to run your tools against it, which hands them Locally's CA, credentials and endpoints:

steps:
  - task: SetupLocally@1
    inputs:
      serviceConnection: my-service-connection
      teamUUID: $(LOCALLY_TEAM_UUID)

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

  - task: TeardownLocally@1
    condition: always()

Anything run outside of locally run (a bare curl, say) needs to trust Locally's CA, which is at $(LOCALLY_TLS_CA_FILE_PATH).

SetupLocally@1 sets the following variables for later steps:

The OIDC token and the CI Key are never set as variables: they're only passed to the locally processes that sign in.

Caching plugins

The GitHub Action caches the plugin directory itself. An Azure Pipelines task can't do that, so to avoid downloading plugins on every run, add the Cache@2 task before SetupLocally@1:

steps:
  - 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

Include the Locally version and the plugin set in the key, so that changing either starts a fresh cache.

Example: Using InstallLocallyPlugins@1

Use this task to install Locally plugins later in a job, for example after running SetupLocally@1 with plugins: none. It requires SetupLocally@1 to have run earlier in the job, and reuses its sign-in.

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

As above, pluginsList takes one plugin per line or a comma-separated list.

The full list of arguments:

¹ With authentication: serviceConnection, exactly one of teamUUID or userUUID must be resolvable (via input or inherited variable) for any value of plugins other than none. Setting both fails.

See tasks/InstallLocallyPluginsV1/task.json for the full input reference.

Example: Using TeardownLocally@1

Use this task as the final step of any job that called SetupLocally@1. It stops locally ci, removes the *.locally DNS configuration added by configureDNS, and, on job failure, uploads ci.log as a pipeline artifact for debugging.

On self-hosted agents this matters: without it, the agent is left routing *.locally to Locally's DNS port after Locally has stopped.

steps:
  - task: TeardownLocally@1
    condition: always()
    # inputs:
    #   uploadLogsOnFailure: true  # default

The full list of arguments:

The artifact is named locally-ci-log-<job name>-<job attempt>, since artifact names have to be unique within a run.

See tasks/TeardownLocallyV1/task.json for the full input reference.

Example: Using SaveLocallySnapshot@1

Use this task to take a snapshot of all of the resources and data in Locally, to load again later or to hand to someone else. It requires SetupLocally@1 to have run earlier in the job, and reuses its sign-in. Snapshots need the Standard plan or above, and sharing them with a team needs the Team plan or above.

[!WARNING] Snapshots contain the credentials of your resources (Key Vault values, keys, passwords). Anyone who can download a pipeline artifact can read an unencrypted snapshot, so set passphrase (from a secret variable) before uploading or sharing one.

steps:
  - task: SaveLocallySnapshot@1
    inputs:
      name: deployed
      upload: artifact
      passphrase: $(LOCALLY_SNAPSHOT_PASSPHRASE)

upload takes a comma-separated list or one entry per line, so upload: artifact, team does both.

The full list of arguments:

Artifact names have to be unique within a run, so when more than one job uploads a snapshot, give each a different name (or artifactName).

Give the step a name to read its output variables from later steps, for example $(save.snapshotPath):

See tasks/SaveLocallySnapshotV1/task.json for the full input reference.

Example: Using LoadLocallySnapshot@1

Use this task to replace everything in Locally with a snapshot - to start a job from an environment that's already been deployed, say, or to put Locally back as it was between two sets of tests. It requires SetupLocally@1 to have run earlier in the job, and reuses its sign-in.

Everything in Locally is replaced, and only if the whole snapshot can be loaded: otherwise it's left as it was. Plugins that the snapshot needs and that aren't installed are installed first.

To put Locally back as it was earlier in the job:

steps:
  - task: SaveLocallySnapshot@1
    inputs:
      name: before

  - script: locally run terraform apply -auto-approve

  - task: LoadLocallySnapshot@1
    inputs:
      snapshot: before

To load a snapshot that another pipeline (or an earlier run) uploaded as an artifact, download it with DownloadPipelineArtifact@2 and give snapshot the folder it was downloaded to. The task loads the one .locallysnap file in that folder:

steps:
  - 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:
      snapshot: $(Pipeline.Workspace)/locally-snapshot
      passphrase: $(LOCALLY_SNAPSHOT_PASSPHRASE)

To load one shared with your Locally Team, which needs the Team plan or above:

steps:
  - task: LoadLocallySnapshot@1
    inputs:
      snapshot: shared-baseline
      source: team
      passphrase: $(LOCALLY_SNAPSHOT_PASSPHRASE)

A team's snapshot is downloaded under a name of its own, loaded, then removed from the agent, so it can't replace a snapshot that's already there.

The full list of arguments:

See tasks/LoadLocallySnapshotV1/task.json for the full input reference.

Development

npm install
npm test               # unit tests
npm run build          # type-check, and bundle each task into tasks/<task>/index.js
npm run package        # out/LocallyBuild.locally-<version>.vsix

Each task is a small entry point (src/setup.ts, src/install-plugins.ts, src/teardown.ts, src/snapshot-save.ts, src/snapshot-load.ts) around a flow (src/*-flow.ts) that's written against an interface rather than the agent, so that the whole flow can be unit tested.

Trying the tasks without publishing the extension

Azure Pipelines only runs tasks that an Organisation has installed, normally from a Marketplace extension. To try a change without publishing, npm run upload installs the tasks straight into one Organisation: it builds them, then uploads each task's folder (its task.json, the bundled index.js and the azure-pipelines-task-lib it needs at runtime) with tfx build tasks upload. Every pipeline in that Organisation can then use them.

It needs a personal access token (User settings -> Personal access tokens) with the Agent Pools (Read & manage) scope:

npm ci
LOCALLY_ADO_ORG_URL=https://dev.azure.com/<organisation> LOCALLY_ADO_PAT=<token> npm run upload

Run it again after changing a task, having bumped Patch in that task's task.json: an Organisation won't take a second upload of the same version, so a task whose version is already there is skipped.

This repository's azure-pipelines.yml tries all five tasks with one job per platform: by default linux_amd64, windows_amd64 and darwin_amd64 (Azure Pipelines' Microsoft-hosted macOS agents are Intel), which you can change when queueing a run. By default it signs in with a CI Key, which needs one secret variable, LOCALLY_CI_KEY. To try OIDC instead, choose serviceConnection when queueing a run and name a Workload Identity Federation service connection; that needs a trust for the service connection in your Locally Account, and the variable LOCALLY_TEAM_UUID. The snapshot tasks need the Locally Account to be on the Standard plan or above.

To remove the tasks again, run npx tfx build tasks delete --task-id <id> --service-url https://dev.azure.com/<organisation> --token <token> for each. The IDs are in each task.json.

Publishing the extension

The publish workflow packages the extension and publishes it to the Visual Studio Marketplace, as the version in vss-extension.json. To release:

1. Bump version in vss-extension.json, and Patch (or Minor) in the task.json of each task that's changed, and update CHANGELOG.md.
2. Once that's on main, push a tag for the version, for example v1.0.1 for 1.0.1. The workflow fails if the tag and the version don't match.

There's no token to store or rotate: it uses the Marketplace's Trusted Publishing, which exchanges GitHub's OIDC token for a Marketplace credential that lasts 15 minutes. That needs a policy on the LocallyBuild publisher's Trusted Publishing page, in the Marketplace's publisher management, with locallybuild as the repository owner, azure-devops-extension as the repository and publish.yml as the workflow.

License

This extension is licensed under Apache-2.0. The Locally CLI it installs is governed by separate terms, see NOTICE.