Whilst there is some documentation, if you're building more involved command line interfaces with Yargs in TypeScript, you may find that you need to do a bit of extra work to get strong typing working well with commands that have builders. In this post, I'll demonstrate how to use Yargs to create statically typed commands with builders in TypeScript.

Before we start, I should say that I'm working with Yargs version 18.0.0 in this post. The type definitions come from Definitely Typed and the version is 17.0.35. However, there is no significant difference in the types between Yargs 17 and 18 and so the difference is not an issue.

As an aside, it's possibly worth mentioning that these days it's possible to go without third party libraries entirely to parse command line arguments thanks to features like parseArgs which have been part of Node.js since version 18. However, Yargs remains a popular choice and is still widely used. I have no plans to replace Yargs in my existing projects just yet.

Getting the builders in​

Let's start with a simple example. Imagine we want to create a command line tool that has a number of commands. Each command has its own options, and we want to use builders to define those options. Here's how we might set that up with Yargs, first we have a main entry point:

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

import { mySimpleCommand } from './commands/mySimpleCommand.js';

const _args = await yargs(hideBin(process.argv))
  .scriptName('my-cli')
  .option('verbose', { alias: 'v', type: 'boolean' })
  .demandCommand(1, 'Please specify a command')
  .command(mySimpleCommand)
  // Add more commands here as needed
  .help().argv;

As we can see, this imports a single command called mySimpleCommand. Let's look at how that command is defined:

import type * as yargs from 'yargs';

export const mySimpleCommand: yargs.CommandModule = {
  command: 'simple-command',
  describe: 'This is a simple command example',
  builder: (b) =>
    b
      .option('myOption', {
        type: 'string',
        demandOption: true,
        description: 'An option for the simple command.',
      })
      .help(),
  handler: async (argv) => {
    const { myOption } = argv; // myOption is `unknown` here

    // Implement your command logic here
  },
};

You can see we have a command called simple-command that has a single option called myOption in the builder. However, if we look at the handler function, we can see that myOption is of type unknown. This is because Yargs does not know the shape of the arguments that will be passed to the handler.

This is the problem we need to solve. Inside the handler, we want to have statically typed access to the options defined in the builder.

Statically typing command builders​

To achieve strong typing, we can define an interface that describes the shape of the arguments for our command. We can then use this interface to type the CommandModule. Here's how we can modify the mySimpleCommand to achieve this:

import type * as yargs from 'yargs';

interface Args {
  myOption: string;
}

export const mySimpleCommand: yargs.CommandModule<unknown, Args> = {
  command: 'simple-command',
  describe: 'This is a simple command example',
  builder: (b) =>
    b
      .option('myOption', {
        type: 'string', // this is important for strong typing
        demandOption: true,
        description: 'An option for the simple command.',
      })
      .help(),
  handler: async (argv) => {
    const { myOption } = argv; // myOption is now `string`

    // Implement your command logic here
  },
};

There's three things to note here:

1. We've defined an Args interface that describes the shape of the arguments for the command.
2. We've updated the CommandModule type to use Args as the second type, which defines the return type of the builder.
3. In the builder, we've specified the type of myOption as string. This is crucial for strong typing to work correctly. Without this we will have compilation errors from TypeScript.

Now we have statically typed access to myOption inside the handler. Yay!

Sharing options among commands and builders​

It's not unusual to have options that are shared among multiple commands. Imagine a common option that all commands need to use. How can we share that option definition among multiple commands while maintaining strong typing? We can achieve this by defining a shared interface for the common options and a function that adds those options to a builder. Here's how we can do that:

export interface SharedOptions {
  someSharedOption: string;
  // other shared options could go here
}

export function getSharedOptions<T>(y: yargs.Argv<T>) {
  return y.option('someSharedOption', {
    type: 'string',
    demandOption: true,
  });
  // other shared options could go here
}

Then, in our command files, we can import the interface and the function and use them like this:

import type * as yargs from 'yargs';
import { type SharedOptions, getSharedOptions } from './sharedOptions.js';

interface Args extends SharedOptions {
  myOption: string;
}

export const mySimpleCommand: yargs.CommandModule<unknown, Args> = {
  command: 'simple-command',
  describe: 'This is a simple command example',
  builder: (b) =>
    getSharedOptions(b)
      .option('myOption', {
        type: 'string',
        demandOption: true,
        description: 'An option for the simple command.',
      })
      .help(),
  handler: async (argv) => {
    const { myOption, someSharedOption } = argv;
    // Now you have statically typed access to myOption and someSharedOption

    // Implement your command logic here
  },
};

By following this pattern, we can create statically typed commands with builders in Yargs while also sharing common options among multiple commands.

It's a beautiful pattern that sparks joy in my soul. Happy coding!

There's also more technical reasons to care about commit messages. For example, if you're using a tool like semantic-release to automate your release process, it relies on conventional commit messages to determine the next version number and generate release notes. It turns out that Azure DevOps has some challenges when it comes to maintaining a git commit history of conventional commits, especially when merging pull requests. By default, Azure DevOps uses a commit strategy that creates a merge commit with a message like "Merge PR 123: Title of pull request". This is acts against conventional commits.

You can use the UI to change the commit message when completing a pull request, but it's very easy to forget to do this. And if you're using squash merges, you lose the individual commit messages from the feature branch, which can be a problem if you're trying to maintain a history of conventional commits.

There is a way to bend Azure DevOps to our will; to allow us to control our commit messages. In this post, I'll show you how to do just that using the Azure DevOps API, some TypeScript and build validations. The fact this mechanism lives in a build validation means you cannot forget to set the commit message. That's the feature.

This post is not, in fact, specifically about using conventional commits. That's just a common use case. Rather this post is about being able to control the commit message when merging pull requests in Azure DevOps.

The approach​

The internet has been angry about Azure DevOps pull request commit messages for a while. There are feature requests which have been open since 2018 and Stack Overflow questions on the topic.

Azure DevOps very rarely gets new features these days, and so it's unlikely that we'll see any changes here. However, there is one avenue that is open to us. Azure DevOps has the ability for a pull request to be set to autocomplete, which means that it will automatically merge when all policies are satisfied. This is useful for ensuring that the pull request is merged without manual intervention once it meets the requirements. For example when build validations have passed, and the required reviewers have approved.

I've written about merging pull requests and setting autocomplete with the Azure DevOps API previously. We're going to build on that knowledge here, but add in the magic of setting the merge commit message when we set the pull request to autocomplete. This is achieved by the pull requests API. It allows us to update a pull request and set it autocomplete with a specific message commit message.

This should allow us to go from commits like this:

To commits like this:

I should say that I'm using conventional commits as my commit message style, but you can use whatever style you like. The important thing is that you have control over the commit message.

The code​

We're going to write a script that can be run in a build validation pipeline. This script will set the pull request to autocomplete with a specific merge commit message. This means that if you use conventional commits, you'll get to maintain a history of conventional commits in your git history.

Before we dive into the full code, here's the bit that does the magic of setting the merge commit message when setting the pull request to autocomplete:

const updateData = {
  autoCompleteSetBy: {
    id: authenticatedUser.id,
  },
  completionOptions: {
    mergeStrategy: 'squash',
    mergeCommitMessage: 'feat: conventional commit message', // <- set your commit message here
  },
};

const response = await fetch(
  `https://dev.azure.com/${org}/${project}/_apis/git/repositories/${repo}/pullrequests/${pullRequestId}?api-version=7.1`,
  {
    method: 'PATCH',
    headers: defaultHeaders,
    body: JSON.stringify(updateData),
  },
);

Here we are:

• Setting the autoCompleteSetBy property to the authenticated user. This is required when setting a pull request to autocomplete.
• Setting the completionOptions.mergeStrategy to squash. You can change this to rebase or noFastForward if you prefer those strategies.
• Setting the completionOptions.mergeCommitMessage. This is where we set our conventional commit message. Or if you wanted to use a different style, you could set it to whatever you like.

The full TypeScript script​

Now that we understand the principle, here's the full set-autocomplete-and-commit-message.ts script that you can use in your build validation pipeline:

import { Buffer } from 'buffer';
import { parseArgs } from 'util';

interface LocationData {
  authenticatedUser?: AuthenticatedUser;
}

interface AuthenticatedUser {
  customDisplayName?: string;
  id: string;
  providerDisplayName: string;
}

function getArgs() {
  const { values } = parseArgs({
    options: {
      token: {
        type: 'string',
        short: 't',
        description: 'Personal Access Token for Azure DevOps API',
      },
      'pr-id': {
        type: 'string',
        short: 'i',
        description: 'Pull Request ID',
      },
      org: {
        type: 'string',
        short: 'o',
        description: 'Azure DevOps organization name',
      },
      project: {
        type: 'string',
        short: 'j',
        description: 'Azure DevOps project name',
      },
      repo: {
        type: 'string',
        short: 'r',
        description: 'Repository name',
      },
    },
  });

  const token = values.token;
  const currentPullRequestId = values['pr-id'];
  const org = values.org
    ?.replace('https://dev.azure.com/', '')
    .replace('/', '');
  const project = values.project;
  const repo = values.repo;

  if (!token) {
    throw new Error('PAT token must be provided using --token');
  }
  if (!currentPullRequestId) {
    throw new Error('Pull Request ID must be provided using --pr-id');
  }
  if (!org) {
    throw new Error('Organization must be provided using --org');
  }
  if (!project) {
    throw new Error('Project must be provided using --project');
  }
  if (!repo) {
    throw new Error('Repository must be provided using --repo');
  }

  return { token, currentPullRequestId, org, project, repo };
}

async function getAuthenticatedUser(
  org: string,
  defaultHeaders: Record<string, string>,
) {
  console.log('Fetching authenticated user info...');

  const connectionDataResponse = await fetch(
    `https://dev.azure.com/${org}/_apis/ConnectionData?api-version=7.2-preview.1`,
    {
      method: 'GET',
      headers: defaultHeaders,
    },
  );

  if (!connectionDataResponse.ok) {
    const errorText = await connectionDataResponse.text();
    throw new Error(
      `Failed to fetch connection data: HTTP ${String(connectionDataResponse.status)}: ${errorText}`,
    );
  }

  const connectionData = (await connectionDataResponse.json()) as LocationData;

  const authenticatedUser = connectionData.authenticatedUser;

  if (!authenticatedUser?.id) {
    throw new Error('Could not determine authenticated user');
  }

  console.log(
    `Authenticated as: ${authenticatedUser.customDisplayName ?? authenticatedUser.providerDisplayName} (ID: ${authenticatedUser.id})`,
  );

  return authenticatedUser;
}

/**
 * Set the merge commit message for a pull request using squash merge strategy
 */
async function setMergeCommitMessageAndAutocomplete({
  pullRequestId,
  mergeCommitMessage,
  token,
  org,
  project,
  repo,
}: {
  pullRequestId: string;
  mergeCommitMessage: string;
  org: string;
  project: string;
  repo: string;
  token: string;
}) {
  const defaultHeaders = {
    Authorization: `Basic ${Buffer.from(`:${token}`).toString('base64')}`,
    'Content-Type': 'application/json',
  };

  const authenticatedUser = await getAuthenticatedUser(org, defaultHeaders);

  console.log(
    `Setting autocomplete and merge commit message for PR #${pullRequestId} as ${authenticatedUser.customDisplayName ?? authenticatedUser.providerDisplayName} (${authenticatedUser.id})...`,
  );

  const updateData = {
    autoCompleteSetBy: {
      id: authenticatedUser.id,
    },
    completionOptions: {
      mergeStrategy: 'squash',
      mergeCommitMessage,
    },
  };

  const response = await fetch(
    `https://dev.azure.com/${org}/${project}/_apis/git/repositories/${repo}/pullrequests/${pullRequestId}?api-version=7.1`,
    {
      method: 'PATCH',
      headers: defaultHeaders,
      body: JSON.stringify(updateData),
    },
  );

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(
      `Failed to set autocomplete and merge commit message: HTTP ${String(response.status)}: ${errorText}`,
    );
  }

  console.log(
    `Successfully set autocomplete and merge commit message for PR #${pullRequestId}`,
  );
}

async function main() {
  const { token, currentPullRequestId, org, project, repo } = getArgs();

  await setMergeCommitMessageAndAutocomplete({
    pullRequestId: currentPullRequestId,
    mergeCommitMessage: 'feat: conventional commit message', // <- set your commit message here
    token,
    org,
    project,
    repo,
  });
}

main().catch((err: unknown) => {
  const errorMessage =
    err instanceof Error ? err.message : 'Unknown error occurred';
  console.error(`[ERROR] ${errorMessage}`);
  throw err;
});

This can also be run locally with node ./set-autocomplete-and-commit-message.ts --token [PAT TOKEN WITH SCOPES: vso.code_write and vso.identity] --pr-id [PULL_REQUEST_ID] --org [NAME_OF_ORGANISATION] --project [NAME_OF_PROJECT] --repo [NAME_OF_REPOSITORY]. You'll need Node.js 24 or later to run this. (And yes, you can run TypeScript files directly with Node.js these days).

The thing I haven't included here is how you determine the mergeCommitMessage. In my case, I use the title of the pull request as the commit message. You can fetch the pull request details using the Azure DevOps API and extract the title. I left this out for brevity, but you can easily add it in. Or use whatever logic you like to determine the commit message. The point is that you have control over it.

The build validation pipeline​

Now we have our script, we need to run it in a build validation pipeline. Here's an example of an Azure DevOps pipeline that runs the script:

trigger: none

pool:
  vmImage: ubuntu-latest

variables:
  isPullRequest: ${{ eq(variables['Build.Reason'], 'PullRequest') }}

stages:
  - stage: AutoCompleteAndCommitMessage
    displayName: Set autocomplete and commit message
    condition: ${{ variables['isPullRequest'] }}
    jobs:
      - job:
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: 24
            displayName: Install Node.js

          - bash: node ./scripts/set-autocomplete-and-commit-message.ts --token $(System.AccessToken) --pr-id $(System.PullRequest.PullRequestId) --org "$(System.CollectionUri)" --project "$(System.TeamProject)" --repo "$(Build.Repository.Name)"
            displayName: Set autocomplete and commit message

Crucially, this pipeline is triggered only for pull requests; the System.PullRequest.PullRequestId is only available in build validations run as part of a pull request. The pipeline installs Node.js 24 and then runs our script, passing in the necessary parameters. The System.AccessToken is used to authenticate with the Azure DevOps API, so make sure that the pipeline has the necessary permissions to use it.

Conclusion​

And that's it! With this setup, you can maintain a git commit history of conventional commits in Azure DevOps, even when merging pull requests. By using the Azure DevOps API to set the merge commit message when setting a pull request to autocomplete, you can ensure that your commit messages are meaningful and consistent.

I'm using the Azure DevOps Client for Node.js; but if you want to use the REST API directly, you can do that too. The principles are the same, but you'll need to make HTTP requests instead of using the client library.

To get up and running with the Azure DevOps Client for Node.js, you can see how we work with it in this post on dynamic required reviewers in Azure DevOps post. This will help you set up your environment and authenticate with Azure DevOps.

If you'd like to read about setting commit messages when merging pull requests in Azure DevOps, you can check out my post on merging pull requests with conventional commits in Azure DevOps.

Merging a pull request​

To merge a pull request with the API, you need to use the GitApi class from the Azure DevOps Client for Node.js. Here's what merging a pull request looks like:

async function mergePullRequest({
  gitApi,
  repositoryName,
  pullRequest,
  projectName,
}: {
  gitApi: IGitApi;
  repositoryName: string;
  pullRequest: GitPullRequest;
  projectName: string;
}): Promise<void> {
  try {
    await gitApi.updatePullRequest(
      {
        status: PullRequestStatus.Completed,
        lastMergeSourceCommit: pullRequest.lastMergeSourceCommit,
        completionOptions: {
          mergeStrategy: GitPullRequestMergeStrategy.Squash,
        },
      },
      /** repositoryId */ repositoryName,
      pullRequest.pullRequestId!,
      /** project */ projectName,
    );
    console.log(
      `✅ Successfully merged pull request ${pullRequest.pullRequestId}`,
    );
  } catch (error) {
    const errorMessage = `❌ Failed to merge pull request ${pullRequest.pullRequestId}`;
    console.error(errorMessage, error);
  }
}

This expects that you provide the gitApi instance, the name of the repository, the pull request object, and the project name. The mergeStrategy is set to Squash, but you can change it to Rebase or NoFastForward if you prefer those strategies.

If you have policies that restrict your merge type, you must pick the merge strategy that complies with those policies. For example, if your project requires squash merges, you should use GitPullRequestMergeStrategy.Squash. AKA the one true merge strategy.

Setting a pull request to autocomplete​

Setting a pull request to autocomplete means that it will automatically merge when all policies are satisfied. This is useful for ensuring that the pull request is merged without manual intervention once it meets the requirements. For example when build validations have passed, and the required reviewers have approved.

Here's how you can set a pull request to autocomplete:

async function setPullRequestToAutocomplete({
  gitApi,
  locationsApi,
  repositoryName,
  pullRequest,
  projectName,
}: {
  gitApi: IGitApi;
  locationsApi: ILocationsApi;
  repositoryName: string;
  pullRequest: GitPullRequest;
  projectName: string;
}): Promise<void> {
  if (pullRequest.autoCompleteSetBy) {
    return;
  }

  try {
    const { authenticatedUser } = await locationsApi.getConnectionData();

    console.log(
      `Setting pull request ${pullRequest.pullRequestId} to auto-complete with squash merge as ${authenticatedUser?.providerDisplayName} (${authenticatedUser?.id})`,
    );

    await gitApi.updatePullRequest(
      {
        autoCompleteSetBy: {
          id: authenticatedUser?.id,
        },
        completionOptions: {
          mergeStrategy: GitPullRequestMergeStrategy.Squash,
        },
      },
      /** repositoryId */ repositoryName,
      pullRequest.pullRequestId!,
      /** project */ projectName,
    );
    console.log(
      `✅ Successfully set pull request ${pullRequest.pullRequestId} to auto-complete`,
    );
  } catch (error) {
    const errorMessage = `❌ Failed to set pull request ${pullRequest.pullRequestId} to auto-complete`;
    console.error(errorMessage, error);
  }
}

What might be surprising about this code is that you have explicitly provide your user id when setting the pull request to autocomplete. The unlovely aspect of this is that you need to discover that id somehow. We achieve it here by fetching the authenticated user from the locationsApi.

Once you have the user id, you can set the autoCompleteSetBy property of the pull request to that user id. This will allow the pull request to be set to autocomplete. Again we must specify the mergeStrategy so it knows how to merge when the time comes.

Conclusion​

In this post, we've seen how to merge a pull request and set it to autocomplete using the Azure DevOps Client for Node.js. This can be a powerful way to automate your workflow and ensure that pull requests are merged when they meet the necessary criteria.

I'm personally using this in build validation pipelines to ensure that pull requests are merged automatically when all policies are satisfied. This helps to streamline the development process and reduce manual intervention.

I build a lot of SPA style applications that run JavaScript / TypeScript on the front end and C# / ASP.NET on the back end. The majority of those apps require some kind of authentication. In fact I'd struggle to think of many apps that don't. This post will walk through how to integrate ASP.NET authentication with the Static Web Apps CLI local authentication emulator to achieve a great local development setup. Don't worry if that doesn't make sense right now, once we have walked through the setup, it will.

This post builds somewhat on posts I've written about using the Static Web Apps CLI with the Vite proxy server with for enhanced performance and how to use the --api-location argument to connect to a separately running backend API. However, you need not have read either post to understand what we're doing.

We're going to first walk through what we're trying to achieve, and then we'll walk through the steps to get there. When it comes to implementation, we're going to use Vite as our front end server, and ASP.NET as our back end server. The Static Web Apps CLI will be used for local authentication emulation.

Local authentication choices​

When we're building an application, let's think about the options that we have, with regards to our local development setup. It's pretty typical for applications to use some kind of third party authentication provider, rather than providing their own. This could be Okta, Microsoft Entra / Azure AD, Auth0 or something else.

It's possible to configure a local development setup which integrates with a third party authentication provider. However, is that wise? Do you want to couple your ability to be able to test scenarios on your local machine, to a server, somewhere out there on the internet? You certainly can. It typically involves setting a redirect URI on the authentication provider to http://localhost:5173 (or wherever your local setup runs).

But it is inconvenient to get that set up in the first place. And even once it is set up, you're then coupled to being online whenever you're testing locally. We're offline more than we appreciate. I'm writing these words on an aeroplane which is currently flying over Botswana. I have no internet access right now. But as you've gathered, I'm on my computer and I'm able to do things. How? Because I'm using the Azure Static Web Apps CLI local authentication emulator for local development.

That's what this post is about. How to use the Static Web Apps CLI local authentication emulator with ASP.NET authentication to enable a great (and offline-first) local development setup.

What is the Static Web Apps CLI?​

We should probably talk about what the Static Web Apps CLI is. It describes itself as:

The Static Web Apps (SWA) CLI is an open-source commandline tool that streamlines local development and deployment for Azure Static Web Apps.

It's original purpose was to provide a local development server for an Azure service known as Azure Static Web Apps. However, it has a number of features that make it useful for general web application development. For example, it can be used to proxy requests to a backend API server, and it can also be used to emulate authentication.

We're going to use the authentication emulator to provide a local authentication server whilst we're developing. Just that piece of functionality; we're intentionally only using a subset of the Static Web Apps CLI functionality.

Incidentally, there are alternatives. I'm aware of one other local authentication emulator, which is the Firebase Authentication Emulator. This could likely be used in a similar way. However, we'll be using the Static Web Apps CLI local authentication emulator.

How does the Static Web Apps CLI local authentication emulator work?​

When running the Static Web Apps start command, it surfaces login endpoints at this location: http://localhost:4280/.auth/login/<PROVIDER_NAME>. <PROVIDER_NAME> is the name of the authentication provider you want to use. This might be aad, github etc. If you look at the code (and you can here) you'll realise that the <PROVIDER_NAME> can actually be any string; it's not limited to the names of the authentication providers that are supported by Azure Static Web Apps. So if you want to use an arbitary name like potato as the provider name, you can do that. In terms of emulation, it doesn't matter what the provider name is.

When started, the CLI will serve a local authentication UI at this endpoint which looks like this:

When you hit the Login button, it will use the form data to create a fake user and set a cookie in your browser named StaticWebAppsAuthCookie. That cookie will look something like this:

And whilst it looks like a JWT, it isn't. It's actually a base64 encoded string which contains the user information that you provided in the form. In fact you can see what it is by flipping open the browser devtools and running this code in the console after you have hit the Login button:

JSON.parse(
  atob(
    document.cookie
      .split('; ')
      .find((row) => row.startsWith('StaticWebAppsAuthCookie='))
      ?.split('=')[1],
  ),
);

This will acquire the cookie that has just been created by the Static Web Apps CLI local authentication emulator from your browser. It then decodes it and parses the JSON string to get the user information that you provided in the form. It produces something like this:

{
  "userId": "4a27b7326639199f5de91c4b9a62531b",
  "userRoles": ["anonymous", "authenticated", "other-role"],
  "claims": [{ "typ": "MyId", "val": "123456789" }],
  "identityProvider": "couldbeanything",
  "userDetails": "megan.s@thing.com"
}

This cookie will be sent to your backend API server with every request.

How is our solution going to work?​

To make a working development setup, we need three things:

1. A front end server (Vite)
2. A back end server (ASP.NET)
3. A local authentication server (Static Web Apps CLI)

We'll bring these three things together to create a local development setup that allows us to develop our application locally, with authentication. This diagram shows how the three components will work together:

From the developer's browser, HTTP requests will be sent to the Vite server running on http://localhost:5173. The Vite server will proxy authentication emulation requests to the Static Web Apps CLI local authentication emulator running on http://localhost:4280. All other requests will be proxied to the ASP.NET backend server running on http://localhost:5000.

This setup means that the cookie that is set by the Static Web Apps CLI local authentication emulator will be shared with the ASP.NET backend server through the Vite proxy mechanism. So to make the ASP.NET authentication work, we need to make sure that the ASP.NET server is configured to accept this cookie and use it to authenticate the user.

Time to implement​

Now that we've talked about what we're trying to achieve, let's walk through the steps to get there. We'll need both the .NET SDK and Node.js installed on our machine. From here on out it's code. The full example can be found in this GitHub repository.

We'll start by creating a new Vite project in a folder we'll call AppFrontEnd. We'll use the React + TypeScript template. You can use whatever template you like:

npm create vite@latest AppFrontEnd -- --template react-ts

Next we'll create a new ASP.NET project in a folder we'll call AppBackEnd:

dotnet new web -n AppBackEnd

And we'll initialise a package.json in the root of our project:

npm init -y

This package.json will be used as a general purpose task runner later on.

Setting up the back end​

We'd first like to adjust the port that our ASP.NET server runs on in development. We'll update the launchSettings.json file to look like this:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

This will set the ASP.NET server to run on http://localhost:5000 in development. You can run the server with dotnet run.

We need to build an AuthenticationHandler that will accept the cookie set by the Static Web Apps CLI local authentication emulator. This is a custom authentication handler that will be used to authenticate users based on the cookie set by the Static Web Apps CLI local authentication emulator. So here the StaticWebAppsCLIAuthentication.cs in all its glory:

using System.Security.Claims;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Json.Serialization;

using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.Options;

namespace AppBackEnd;

public static class StaticWebAppsCLIAuthentication
{
    public const string STATICWEBAPPSCLIAUTH_SCHEMENAME = "StaticWebAppsCLIAuthScheme";

    public static AuthenticationBuilder AddStaticWebAppsCLIAuth(
        this AuthenticationBuilder builder,
        Action<AuthenticationSchemeOptions>? configure = null)
    {
        if (configure == null) configure = o => { };

        return builder.AddScheme<AuthenticationSchemeOptions, StaticWebAppsCLIAuthenticationHandler>(
            STATICWEBAPPSCLIAUTH_SCHEMENAME,
            STATICWEBAPPSCLIAUTH_SCHEMENAME,
            configure
        );
    }
}

public class StaticWebAppsCLIAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    public StaticWebAppsCLIAuthenticationHandler(
        IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder)
        : base(options, logger, encoder)
    {
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        try
        {

            var principal = await MakeClaimsPrincipalFromHeaderOrCookie(
                // eg eyJ1c2VySWQiOiIwMTA2ZWMwYmU2MjAwNDM5YjY5ODc3NTFiOGJmNmU3YSIsInVzZXJSb2xlcyI6WyJhbm9ueW1vdXMiLCJhdXRoZW50aWNhdGVkIl0sImNsYWltcyI6W3sidHlwIjoibmFtZSIsInZhbCI6IkF6dXJlIFN0YXRpYyBXZWIgQXBwcyJ9XSwiaWRlbnRpdHlQcm92aWRlciI6ImFhZCIsInVzZXJEZXRhaWxzIjoiam9obm55cmVpbGx5In0
                Context.Request.Cookies["StaticWebAppsAuthCookie"] ??
                // eg eyJ1c2VySWQiOiIwMTA2ZWMwYmU2MjAwNDM5YjY5ODc3NTFiOGJmNmU3YSIsInVzZXJSb2xlcyI6WyJhbm9ueW1vdXMiLCJhdXRoZW50aWNhdGVkIl0sImlkZW50aXR5UHJvdmlkZXIiOiJhYWQiLCJ1c2VyRGV0YWlscyI6ImpvaG5ueXJlaWxseSJ9
                // for reasons that are unclear, the X-MS-CLIENT-PRINCIPAL header presently excludes claims; see https://github.com/Azure/static-web-apps-cli/blob/062fb288d34126a095be6f3e1dc57fe5adb3f4bf/src/msha/handlers/function.handler.ts#L38-L42
                Context.Request.Headers["X-MS-CLIENT-PRINCIPAL"].FirstOrDefault()
            );

            if (principal == null)
                return AuthenticateResult.NoResult();

            Context.User = principal;

            return AuthenticateResult.Success(new AuthenticationTicket(principal, principal.Identity?.AuthenticationType ?? "unknown"));
        }
        catch (Exception ex)
        {
            return AuthenticateResult.Fail(ex);
        }
    }

    private async Task<ClaimsPrincipal?> MakeClaimsPrincipalFromHeaderOrCookie(string? headerOrCookie)
    {
        if (string.IsNullOrEmpty(headerOrCookie))
            return null;

        var decodedBytes = Convert.FromBase64String(headerOrCookie);
        using var memoryStream = new MemoryStream(decodedBytes);
        var staticWebAppClientPrinciple = await JsonSerializer.DeserializeAsync<StaticWebAppsCLIClientPrinciple>(memoryStream);

        if (staticWebAppClientPrinciple == null ||
            string.IsNullOrWhiteSpace(staticWebAppClientPrinciple.UserDetails) ||
            string.IsNullOrWhiteSpace(staticWebAppClientPrinciple.UserId))
            return null;

        var claims = DefaultMapClaims(staticWebAppClientPrinciple);

        var principal = new ClaimsPrincipal();
        principal.AddIdentity(new ClaimsIdentity(
            claims,
            authenticationType: staticWebAppClientPrinciple.IdentityProvider ?? "unknown",
            nameType: ClaimTypes.Email,
            roleType: ClaimTypes.Role
        ));

        return principal;
    }

    /// <summary>
    /// Method takes the StaticWebAppClientPrinciple and produces a list of claims constructed
    /// from the claims, user details and user roles
    /// </summary>
    static Claim[] DefaultMapClaims(StaticWebAppsCLIClientPrinciple staticWebAppClientPrinciple)
    {
        var claims = new List<StaticWebAppsCLIClaim>();
        if (!string.IsNullOrWhiteSpace(staticWebAppClientPrinciple.UserDetails))
        {
            claims.Add(new StaticWebAppsCLIClaim
            {
                Type = "preferred_username",
                Value = staticWebAppClientPrinciple.UserDetails
            });
            claims.Add(new StaticWebAppsCLIClaim
            {
                Type = ClaimTypes.Email,
                Value = staticWebAppClientPrinciple.UserDetails
            });
            claims.Add(new StaticWebAppsCLIClaim
            {
                Type = ClaimTypes.Name,
                Value = staticWebAppClientPrinciple.UserDetails
            });
        }

        if (staticWebAppClientPrinciple.Claims != null)
        {
            claims.AddRange(staticWebAppClientPrinciple.Claims);
        }

        var mappedClaims = claims.Select(claim => new Claim(claim.Type, claim.Value));
        // translate the user roles into claims with the type ClaimTypes.Role
        // eg "userRoles": ["anonymous", "authenticated"]
        var userRoleClaims = staticWebAppClientPrinciple.UserRoles?.Select(role =>
            new Claim(ClaimTypes.Role, role)) ?? [];

        Claim[] combinedClaims = [..mappedClaims, ..userRoleClaims];

        return combinedClaims;
    }
}

/// <summary>
/// This is the JSON object that is decoded from either the
/// StaticWebAppsAuthCookie cookie or the X-MS-CLIENT-PRINCIPAL header
/// when working with the Static Web Apps CLI local authentication emulator.
///
/// The claims element is not present on the X-MS-CLIENT-PRINCIPAL header
///
/// {
///     "userId": "9b516349fcf5caf60f715703d8804aa7",
///     "userRoles": [
///         "anonymous",
///         "authenticated"
///     ],
///     "claims": [{"typ":"blarg","val":"Azure Static Web Apps"}],
///     "identityProvider": "aad",
///     "userDetails": "someone.name@company.com"
/// }
/// </summary>
public class StaticWebAppsCLIClientPrinciple
{
    /// <summary>
    /// User Id
    /// </summary>
    [JsonPropertyName("userId")]
    public string? UserId { get; set; }

    /// <summary>
    /// User roles
    /// </summary>
    [JsonPropertyName("userRoles")]
    public IEnumerable<string>? UserRoles { get; set; }

    /// <summary>
    /// Identity provider typically "aad"
    /// </summary>
    [JsonPropertyName("identityProvider")]
    public string? IdentityProvider { get; set; }

    /// <summary>
    /// User details typically email address
    /// </summary>
    [JsonPropertyName("userDetails")]
    public string? UserDetails { get; set; }

    /// <summary>
    /// Claims for the user
    /// </summary>
    [JsonPropertyName("claims")]
    public IEnumerable<StaticWebAppsCLIClaim>? Claims { get; set; } = [];
}

public class StaticWebAppsCLIClaim
{
    /// <summary>
    /// Type of claim eg "name"
    /// </summary>
    [JsonPropertyName("typ")]
    public string Type { get; set; } = string.Empty;
    /// <summary>
    /// Value of claim eg "Someone Name"
    /// </summary>
    [JsonPropertyName("val")]
    public string Value { get; set; } = string.Empty;
}

Whilst there's a good amount of code here, what we're actually doing is relatively simple:

• We define a custom authentication scheme called StaticWebAppsCLIAuthScheme
• We define a custom authentication handler called StaticWebAppsCLIAuthenticationHandler. The handler will decode the cookie and create a ClaimsPrincipal object that contains the user information it. This will be used to authenticate users based on the cookie that has been set by the Static Web Apps CLI local authentication emulator. If the StaticWebAppsAuthCookie cookie is not detected, the handler will fallback to the X-MS-CLIENT-PRINCIPAL header. (This should never happen in practice, but it's there for completeness.)

With our handler in place, we need to update the Program.cs file in the AppBackEnd project to use it. We'll also add a /api/me endpoint to test the authentication. So the modified Program.cs file looks like this:

using AppBackEnd;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    // in development, we want to use the Static Web Apps CLI authentication scheme
    builder.Services
        .AddAuthentication(StaticWebAppsCLIAuthentication.STATICWEBAPPSCLIAUTH_SCHEMENAME)
        .AddStaticWebAppsCLIAuth();
}
else
{
    // in production we will use an alternative authentication scheme
    // ...
}

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");

app.MapGet("/api/me", (context) => {
    var user = context.User;
    var roleClaimType = user.Identities.First().RoleClaimType;

    var userDetails = new {
        user.Identity?.Name,
        user.Identity?.IsAuthenticated,
        Claims = user.Claims.Select(claim => new { claim.Type, claim.Value }).ToArray(),
    };

    return context.Response.WriteAsJsonAsync(userDetails);
});

app.Run();

I haven't included the production authentication scheme here; that will be specific to your application. The important part is that we are using the StaticWebAppsCLIAuthentication scheme in only in development.

Let's test this works. We'll start the ASP.NET server with dotnet run. Then we'll use the curl command to call the /api/me endpoint:

curl http://localhost:5000/api/me --cookie "StaticWebAppsAuthCookie=eyJ1c2VySWQiOiIxNDdmMTVjNmFiODBhNmY3NjJhOWQyZDRmNzczNzUwOSIsInVzZXJSb2xlcyI6WyJhbm9ueW1vdXMiLCJhdXRoZW50aWNhdGVkIiwib3RoZXItcm9sZSJdLCJjbGFpbXMiOlt7InR5cCI6Ik15SWQiLCJ2YWwiOiIxMjM0NTY3ODkifV0sImlkZW50aXR5UHJvdmlkZXIiOiJjb3VsZGJlYW55dGhpbmciLCJ1c2VyRGV0YWlscyI6Im1lZ2FuLnNAdGhpbmcuY29tIn0="

This will return the user information that was set in the cookie by the Static Web Apps CLI local authentication emulator:

{
  "name": "megan.s@thing.com",
  "isAuthenticated": true,
  "claims": [
    {
      "type": "preferred_username",
      "value": "megan.s@thing.com"
    },
    {
      "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "value": "megan.s@thing.com"
    },
    {
      "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "value": "megan.s@thing.com"
    },
    {
      "type": "MyId",
      "value": "123456789"
    },
    {
      "type": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
      "value": "anonymous"
    },
    {
      "type": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
      "value": "authenticated"
    },
    {
      "type": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
      "value": "other-role"
    }
  ]
}

So our authentication mechanism works! Now we just need to set up the Vite server and the Static Web Apps CLI local authentication emulator to provide the full local development experience.

Setting up the front end​

Now we'll move over to the AppFrontEnd folder.

Set up the Static Web Apps CLI​

We'll install the Static Web Apps CLI as a development dependency:

npm install -D @azure/static-web-apps-cli

And we'll add a start script to the package.json file to start the Static Web Apps CLI and the Vite server. The start script will look like this:

{
  "scripts": {
    "start": "swa start http://localhost:5173 --run \"npm run dev\" --api-devserver-url http://127.0.0.1:5000"
  }
}

When run, this will start the Static Web App CLI and the Vite server. The --run argument will start the Vite server, and the --api-devserver-url argument will set the URL of the ASP.NET backend server. We'll create a mechanism for starting the ASP.NET server alongside the front end shortly.

Set up the Vite server​

We already have the Vite server in place, but it needs a little configuration.

I'm now going to borrow from this post on using the Vite proxy server with for enhanced performance. We'll update the vite.config.ts file to add a proxy configuration. The vite.config.ts file will look like this:

import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig({
  // ...
  server: {
    proxy: {
      '/api': {
        // our .NET application is running on port 5000
        target: 'http://127.0.0.1:5000',
        changeOrigin: true,
        autoRewrite: true,
      },
      '/.auth': {
        // the Static Web Apps local auth emulator is running on port 4280
        target: 'http://127.0.0.1:4280',
        changeOrigin: true,
        autoRewrite: true,
      },
    },
  },
});

The code above is responsible for ensuring that requests to the Vite server with the prefix /.auth are proxied to the Static Web Apps CLI local authentication emulator. Requests with the prefix /api (most requests) are proxied to the ASP.NET backend server.

With this in place, the Static Web Apps CLI local authentication emulator will be able to set the StaticWebAppsAuthCookie cookie in the browser, and the Vite server will proxy requests with that cookie to the ASP.NET backend server for use.

Bringing front end and back end together​

We now have a back end and a front end in place. We need both to be running for local development. We mentioned earlier we'd be using the package.json in the root of the project as a task runner.

We'll use the concurrently package to allow us to run both the ASP.NET server and the Static Web Apps CLI local authentication emulator at the same time.

npm install -D concurrently

And we'll update the scripts section of the package.json as follows:

{
  "scripts": {
    "postinstall": "npm run install:frontend && npm run install:backend",
    "install:frontend": "cd AppFrontEnd && npm install",
    "install:backend": "cd AppBackEnd && dotnet restore",
    "start": "concurrently -n \"FE,BE\" -c \"bgBlue.bold,bgMagenta.bold\" \"npm run start:frontend\" \"npm run start:backend\"",
    "start:frontend": "cd AppFrontEnd && npm run start",
    "start:backend": "cd AppBackEnd && dotnet watch run"
  }
}

We can now install all our dependencies (front end and backend) with a single command:

npm install

Then we can start the local development server with:

npm start

If we then go to http://localhost:5173, we should see the Vite server running:

So far, this is just the Vite server. Time to get our login mechanism in place.

Testing the authentication​

We're going to replace the contents of the src/App.tsx file in the AppFrontEnd project with code that will call the /api/me endpoint on the ASP.NET backend server to get the user information from the cookie set by the Static Web Apps CLI local authentication emulator and display it in the browser. If the user is not authenticated, it will show a login link.

A reminder, we're using React and TypeScript for our front end. But that's just because it's my preference; this technique is front end agnostic. You can use whatever framework (or none) that you like.

Our implementation will look like this:

import { useState, useEffect } from 'react';
import './App.css';

interface UserData {
  name: string | null;
  isAuthenticated: boolean;
  claims: { type: string; value: string }[];
}

function App() {
  const [userData, setUserData] = useState<UserData>();

  useEffect(() => {
    async function fetchData() {
      try {
        const response = await fetch('/api/me');
        if (!response.ok) {
          throw new Error('Failed to fetch user data');
        }
        const data = await response.json();
        setUserData(data);
      } catch (error) {
        console.error('Error fetching user data:', error);
      }
    }

    fetchData();
  }, []);

  return (
    <>
      <h1>Static Web Apps CLI:</h1>
      <h2>local authentication emulation with ASP.NET</h2>
      {userData ? (
        userData.isAuthenticated ? (
          <p style={{ textAlign: 'left' }}>
            You are logged in {userData.name} |{' '}
            <a href="/.auth/logout">Log out</a>
            <pre>{JSON.stringify(userData, null, 2)}</pre>
          </p>
        ) : (
          <p>
            <a href="/.auth/login/aad">Log in</a>
          </p>
        )
      ) : (
        <p>Loading user data...</p>
      )}
    </>
  );
}

export default App;

Let's test it! First we'll start our local dev setup with npm start. When we browse to http://localhost:5173, we should see the Vite server running:

If we click the Login link, we'll be taken to the Static Web Apps CLI local authentication emulator. We'll fill in the form and hit Login. This will set the StaticWebAppsAuthCookie cookie in our browser.

We'll be redirected back to the Vite server, and the cookie will be sent to the ASP.NET backend server. The ASP.NET backend server will use the cookie to authenticate the user and return the user information when the browser calls the /api/me endpoint. This will be displayed in the browser:

It works!

Summing up​

This has been a long post, but hopefully it has been useful. We've walked through how to set up a local development environment that uses the Static Web Apps CLI local authentication emulator with ASP.NET authentication. This allows us to develop our application locally, with authentication, without being coupled to a third party authentication provider.

The code built in this post can be found here.

Credits​

• Server icon by Konstantin Velichko from Noun Project (CC BY 3.0)
• Browser icon by syahruni from Noun Project (CC BY 3.0)

I ended up using zipping and unzipping with postinstall and prepare scripts to include these files into my npm package.

This post shows how to use zipping and unzipping with postinstall and prepare scripts to include these files into your npm package.

A little backstory​

I'm currently beavering away on a "create-*-app" tool that generates new projects from a number of available templates. That tool takes the form of a CLI tool built with TypeScript, published as a package to an npm registry and consumed with npx. Significantly, the templates that ship with the CLI take the form of a templates folder in the package, and the folders in those templates include .npmrc and .gitignore files; which are key to the functionality of the templates.

When publishing my npm package, I discovered that the .npmrc and .gitignore files in subfolders were being stripped from the package. After a little research, I happened upon this GitHub issue about npm which describes some of the behaviour I was seeing. After a touch more digging, I came to understand that this behaviour is a result of npm treating the .gitignore and .npmrc files as configuration files rather than part of the package's intended content.

However, given these files are essential to the templates' functionality, I needed to find a way to include them in the package.

I mused with explicitly including the specific files in the files section of the package.json file, but this would have been a maintenance headache. I wanted a more automated solution. Given that I have a single "special" folder called templates that contains all the templates, I pondered whether I could zip the folder on publish and unzip it on install. This would allow me to include the .gitignore and .npmrc files in the templates and have them copied into the new project when the template was used. And if there was another other curious behaviour around publishing, this solution should cover that too.

prepare and postinstall scripts​

I achieved this by using prepare and postinstall scripts in the package.json file.

The prepare and postinstall scripts are two of the lifecycle scripts that npm runs when installing a package. The prepare script runs before the package is packaged and published, and the postinstall script runs after the package is installed. I opted to use these scripts to zip and unzip the templates folder in my package.

I performed the actual zipping and unzipping with some Node.js scripts. We'll look into the implementation of these scripts in a moment, but first please note the scripts we added to the package.json file:

  "scripts": {
    "postinstall": "node ./scripts/postinstall.js",
    "prepare": "node ./scripts/prepare.js"
  },

These scripts contain the paths to the Node.js scripts that perform the zipping and unzipping. The postinstall script runs after the package is installed, and the prepare script runs before the package is packaged and published.

When it comes to zipping and unzipping, I used the adm-zip package. This package provides a simple API for zipping and unzipping files and folders.

prepare.js​

We'll first look at the prepare.js script. This script zips the templates folder in the package into a templates.zip file. The script then writes the zip file to the package's root directory.

import AdmZip from 'adm-zip';
import fs from 'node:fs';
import { fileURLToPath } from 'node:url';

function packTemplates() {
  console.log('prepare running - packing templates');

  const templatesZipPath = fileURLToPath(
    new URL('../templates.zip', import.meta.url),
  );
  const templatesDir = fileURLToPath(new URL('../templates', import.meta.url));

  const zip = new AdmZip();

  console.log(`removing existing ${templatesZipPath}`);
  fs.rmSync(templatesZipPath, {
    force: true,
  });

  console.log(`adding ${templatesDir} to zip file`);
  zip.addLocalFolder(templatesDir);

  console.log(`writing zip to ${templatesZipPath}`);
  zip.writeZip(templatesZipPath);
}

packTemplates();

It also removes any existing templates.zip file in the package's root directory before creating a new one. This is to ensure that the zip file is always up to date.

postinstall.js​

Now we'll look at the postinstall.js script. This script unzips the templates.zip file in the package into a templates folder. The script then writes the unzipped folder to the package's root directory.

import AdmZip from 'adm-zip';
import fs from 'node:fs';
import { fileURLToPath } from 'node:url';

function extractTemplates() {
  console.log('postinstall running - extracting templates');
  const templatesZipPath = fileURLToPath(
    new URL('../templates.zip', import.meta.url),
  );
  const templatesDir = fileURLToPath(new URL('../templates', import.meta.url));

  let templatesExistsAlready = true;
  try {
    fs.accessSync(templatesDir);
  } catch {
    templatesExistsAlready = false;
  }

  if (templatesExistsAlready) {
    console.log('templates already extracted');
    return;
  }

  console.log(`extracting from ${templatesZipPath} to ${templatesDir}`);

  const extractZip = new AdmZip(templatesZipPath);
  extractZip.extractAllTo(templatesDir, /* overwrite */ false);

  console.log('templates extracted');
}

extractTemplates();

You'll notice that the script checks whether the templates folder already exists before unzipping the templates.zip file. This is to ensure that the folder is only unzipped once.

Conclusion​

So here we have a method for including .gitignore and .npmrc files in an npm package. By using zipping and unzipping with postinstall and prepare scripts, we can include these files in the package and have them copied into the new project when the package is installed.

My example is a templates folder - yours could be anything. And likewise if you have other files that are being stripped from your package, you could use this method to include them too.

However, the required reviewers are static. You can set them up in the branch policies, but they don't change dynamically based on the code being altered or the people involved in the pull request. I spent many moons trawling the internet for an answer to this question, and I found that many people were asking the same question. The answer was always the same: "You can't do that."

However, there is a way. It is, hand on heart, marginally clunky. But the clunk is marginal, and more than acceptable. It involves co-opting build validations to achieve the desired effect. In this post, I'll show you how to do that.

Build validations and required reviewers​

Build validations in Azure DevOps are a way to ensure that code meets certain criteria before it is merged into the main branch. They are, crucially, Azure DevOps pipelines that run when a pull request is created or updated. They are typically used to ensure that the code builds successfully, tests pass, linting succeeds etc. Build validations are set up in the branch policies for a repository. It's pretty typical for a repository to have a build validations.

The crucial thing to note is that, typically, build validations must pass before a pull request can be completed. That's how they provide their value; as a control to prevent changes breaking the codebase. What we're going to do, is use this blocking aspect to our advantage. We'll include a new stage in our build validation pipeline that, each time it runs, does one of the following:

1. Dynamically adds a required reviewer to the pull request, if appropriate. The way we decide which reviewers are dynamically added, if any, is down to us to determine. It's entirely flexible. It could be based on the code being changed or the people involved in the pull request, or indeed something else. If no reviewer is added, the pipeline will pass. But if a reviewer is added to the pull request, the pipeline will be made to fail.
2. If a reviewer is determined as required, and has already been assigned, check if the reviewer has approved the pull request. If they have approved, the pipeline will pass. If they haven't approved the pull request, the pipeline will fail.

The thing to pay attention to is that the pipeline will fail if dynamically assigned required reviewers have not given their approval by the end of the pipeline run. This applies equally if the pipeline is running for the first time against a pull request and assigning the reviewers. This means that the pull request cannot be completed until any dynamically assigned required reviewers have approved it.

This is the part that makes your risk and audit teams happy. You cannot circumvent the required reviewers; the pipeline failing will prevent the pull request from being merged / completed until the required reviewers have approved it. This is a way to ensure that the code is reviewed by the appropriate people before it is merged into the main branch.

I mentioned "clunky" earlier. The clunkiness comes from the need to rerun the build validation pipeline in the Azure DevOps UI when the approval has been given. This is because there is no way (that I'm aware of) to trigger the build validation pipeline when a reviewer approval has been provided. So, if the required reviewers approve the pull request, you will need to rerun the build validation pipeline to ensure that it passes and the pull request can be completed.

As long as the failing pipeline provides a clear message about what is required, this is a small price to pay for the ability to have dynamic required reviewers.

Now I've convinced you that this is a good idea, let's look at how to implement it.

Co-opting your existing build validation pipeline​

I'm making an assumption that you already have a build validation pipeline set up for your repository. If you don't, you'll need to set one up first.

To your existing build validation pipeline, you'll need to add a new stage that will run the code to dynamically assign required reviewers:

- stage: DynamicRequiredReviewers
  displayName: Dynamic required reviewers
  dependsOn: [] # This stage does not depend on any other stages and so will run in parallel with the others
  jobs:
    - job:
      steps:
        - task: NodeTool@0
          inputs:
            versionSpec: 22
          displayName: Install Node.js

        - bash: npm ci
          displayName: 'Install dependencies'
          workingDirectory: 'scripts/dynamic-required-reviewers'

        - bash: npm test
          displayName: 'Run tests'
          workingDirectory: 'scripts/dynamic-required-reviewers'

        - bash: npm start -- --sat $(System.AccessToken) --pullRequestId $(System.PullRequest.PullRequestId) --organization $(System.CollectionUri) --repositoryName $(Build.Repository.Name) --projectName $(System.TeamProject)'
          displayName: 'Validate claims'
          workingDirectory: 'scripts/dynamic-required-reviewers'

You can see reference to the scripts/dynamic-required-reviewers directory. This is where we'll put the code that will dynamically assign required reviewers. The code will run in a Node.js environment, so we'll need to install Node.js and the dependencies for the code to run.

You can also see that we're using the System.AccessToken and System.PullRequest.PullRequestId variables. The System.AccessToken is a token that allows the code to interact with the Azure DevOps API, and the System.PullRequest.PullRequestId is the ID of the pull request that the build validation pipeline is running against. We'll use these in our code to dynamically assign required reviewers to the pull request.

We also use the System.CollectionUri, Build.Repository.Name, and System.TeamProject variables to get the organization, repository name, and project name respectively. These will be used to make API calls to Azure DevOps with our token.

Setting up the code to dynamically assign required reviewers​

You'll need to create the scripts/dynamic-required-reviewers directory. In there we're going to add a package.json file to manage our dependencies:

{
  "name": "dynamic-required-reviewers",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": "npm run build && node dist/index.js"
  },
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "azure-devops-node-api": "^15.1.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.8.3"
  }
}