Skip to main content

One post tagged with "Netlify deploy previews"

View All Tags

· 11 min read

I love Netlify deploy previews. This post implements a pull request deployment preview mechanism for Azure Static Web Apps in the context of Azure DevOps which is very much inspired by the Netlify offering.

title image reading "Azure Static Web App Deploy Previews with Azure DevOps" with a Azure, Bicep and Azure DevOps logos

Having a build of your latest pull request which is deployed and clickable from the PR itself is a wonderful developer experience. It reduces friction for testing out changes by allowing you to see the impact from within the PR itself. No checking to see if an environment is free with the rest of the team, then manually running a pipeline and waiting whilst a deployment happens. No. It's all there without you having to lift a finger. I use Netlify deploy previews on my blog and have become accustomed to the delight that is this:

screenshot of a Netlify deploy preview on my latest blog post

I love this and I wanted to implement the "browse the preview" mechanism in Azure DevOps as well, using Azure Static Web Apps. This blog post contains two things:

  1. A pull request deployment environment mechanism using Azure and Azure Pipelines with Bicep.
  2. A mechanism for updating a pull request in Azure DevOps with a link to the deployment environment (the "browse the preview")

It's worth bearing in mind that there's a very similar feature to what we're going to build for 1. in SWAs now called "staging environments" that is presently only available on GitHub and not Azure DevOps:

screenshot of Anthony Chu at Microsoft saying "Unfortunately environments is not yet available for Azure DevOps."

It's possible that in future the deployment environment aspect of this blog post may be rendered redundant by staging environments landing in Azure DevOps. However, the second part, which updates a PR in ADO with a link is probably generally useful. And it may be the case that the approach of provisioning an environment on demand and extracting a URL could be reworked to work with App Service and similar too.

I wrote about using SWAs with Azure DevOps earlier this year. This blog post will take the form of a pull request on the code written in that post. The finished code for this blog post can be found here.

Getting defaultHostName from Static Web Apps

The first thing we're going to do is take the Bicep from that post and tweak it to the following:

param appName string
param repositoryUrl string
param repositoryBranch string

param skuName string = 'Free'
param skuTier string = 'Free'

resource staticWebApp 'Microsoft.Web/[email protected]' = {
name: repositoryBranch == 'main' ? appName : '${appName}-${repositoryBranch}'
location: resourceGroup().location
sku: {
name: skuName
tier: skuTier
}
properties: {
// The provider, repositoryUrl and branch fields are required for successive deployments to succeed
// for more details see: https://github.com/Azure/static-web-apps/issues/516
provider: 'DevOps'
repositoryUrl: repositoryUrl
branch: repositoryBranch
buildProperties: {
skipGithubActionWorkflowGeneration: true
}
}
}

output staticWebAppDefaultHostName string = staticWebApp.properties.defaultHostname // eg gentle-bush-0db02ce03.azurestaticapps.net
output staticWebAppId string = staticWebApp.id
output staticWebAppName string = staticWebApp.name

There's some changes in here. First of all we're using a newer version of the staticSites resource in Azure. You'll also see that we name the resource conditionally now. If we're on the main branch we name it as we did before with appName. But if we aren't then we suffix the name with the repositoryBranch. It's worth knowing that there are restrictions and conventions for Azure resource naming. If you have a branch name that is just alphanumerics and hyphens you'll be fine.

You'll see the output of the Bicep file has changed. Previously we were outputting the apiKey that we used for deployment. This isn't the securest of approaches as, by having this as a deployment output, this data can be accessed by people who share access with your Azure portal. So we're going to use a different (and more secure) approach to acquire this in our pipeline later.

More significantly, we are now outputting the staticWebAppDefaultHostName of our newly provisioned SWA. This is the location where people will be able to view the deployment preview. Since we want to pump that into our pull request description, so people can click on the link, we are going to need this. We're also pumping out the staticWebAppId and staticWebAppName. We'll use the staticWebAppName to acquire the apiKey in our pipeline.

Azure Pipelines tweaks

Now to the pipeline. After the deployment, our updated pipeline is going to acquire the apiKey for deployment like so:

- task: [email protected]
displayName: 'Acquire API key for deployment'
inputs:
azureSubscription: $(serviceConnection)
scriptType: bash
scriptLocation: inlineScript
inlineScript: |
APIKEY=$(az staticwebapp secrets list --name $(staticWebAppName) | jq -r '.properties.apiKey')
echo "##vso[task.setvariable variable=apiKey;issecret=true]$APIKEY"

The above uses the Azure CLI task to acquire the apiKey. It uses jq to pull out the required property from the JSON and writes it as a secret variable in the pipeline to be used in the deployment.

At the end of the pipeline, if we're not on the main branch, the the pipeline is going to run a custom script that will update the PR with the preview URL:

- task: [email protected]
displayName: 'Pull request preview install'
condition: and(succeeded(), ne(variables.isMain, 'true'))
inputs:
command: 'install'
workingDir: pull-request-preview

- task: [email protected]
displayName: 'Pull request preview'
condition: and(succeeded(), ne(variables.isMain, 'true'))
inputs:
command: 'custom'
customCommand: 'run pull-request-preview -- --sat "$(System.AccessToken)" --project "$(System.TeamProject)" --repository "$(Build.Repository.Name)" --systemCollectionUri "$(System.CollectionUri)" --pullRequestId $(System.PullRequest.PullRequestId) --previewUrl "https://$(staticWebAppDefaultHostName)"'
workingDir: pull-request-preview

We haven't written that script yet; we will in a moment.

The complete azure-piplines.yml is below, and you'll notice we've moved all variables save for the subscriptionId into the azure-pipelines.yml and we're using a westeurope location / resource group as at present staticSites is not available everywhere:

pool:
vmImage: ubuntu-latest

variables:
# subscriptionId is a variable defined on the pipeline itself
- name: appName
value: 'our-static-web-app'
- name: location
value: 'westeurope' # at time of writing static sites are available in limited locations such as westeurope
- name: serviceConnection
value: 'azureRMWestEurope'
- name: azureResourceGroup # this resource group lives in westeurope
value: 'johnnyreilly'

steps:
- checkout: self
submodules: true

- bash: az bicep build --file infra/static-web-app/main.bicep
displayName: 'Compile Bicep to ARM'

- task: [email protected]
name: DeployStaticWebAppInfra
displayName: Deploy Static Web App infra
inputs:
deploymentScope: Resource Group
azureResourceManagerConnection: $(serviceConnection)
subscriptionId: $(subscriptionId)
action: Create Or Update Resource Group
resourceGroupName: $(azureResourceGroup)
location: $(location)
templateLocation: Linked artifact
csmFile: 'infra/static-web-app/main.json' # created by bash script
overrideParameters: >-
-repositoryUrl $(Build.Repository.Uri)
-repositoryBranch $(Build.SourceBranchName)
-appName $(appName)
deploymentMode: Incremental
deploymentOutputs: deploymentOutputs

- task: [email protected]
name: 'SetDeploymentOutputVariables'
displayName: 'Set Deployment Output Variables'
inputs:
targetType: inline
script: |
$armOutputObj = '$(deploymentOutputs)' | ConvertFrom-Json
$armOutputObj.PSObject.Properties | ForEach-Object {
$keyname = $_.Name
$value = $_.Value.value

# Creates a standard pipeline variable
Write-Output "##vso[task.setvariable variable=$keyName;]$value"

# Display keys and values in pipeline
Write-Output "output variable: $keyName $value"
}
pwsh: true

- task: [email protected]
displayName: 'Acquire API key for deployment'
inputs:
azureSubscription: $(serviceConnection)
scriptType: bash
scriptLocation: inlineScript
inlineScript: |
APIKEY=$(az staticwebapp secrets list --name $(staticWebAppName) | jq -r '.properties.apiKey')
echo "##vso[task.setvariable variable=apiKey;issecret=true]$APIKEY"

- task: [email protected]
name: DeployStaticWebApp
displayName: Deploy Static Web App
inputs:
app_location: 'static-web-app'
# api_location: 'api'
output_location: 'build'
azure_static_web_apps_api_token: $(apiKey)

- task: [email protected]
displayName: 'Pull request preview install'
condition: and(succeeded(), ne(variables.isMain, 'true'))
inputs:
command: 'install'
workingDir: pull-request-preview

- task: [email protected]
displayName: 'Pull request preview'
condition: and(succeeded(), ne(variables.isMain, 'true'))
inputs:
command: 'custom'
customCommand: 'run pull-request-preview -- --sat "$(System.AccessToken)" --project "$(System.TeamProject)" --repository "$(Build.Repository.Name)" --systemCollectionUri "$(System.CollectionUri)" --pullRequestId $(System.PullRequest.PullRequestId) --previewUrl "https://$(staticWebAppDefaultHostName)"'
workingDir: pull-request-preview

Updating the PR with a preview URL

We want to be able to update our pull request with our deploy URL. To make that happen, we're going to whiz up a little node app using TypeScript, ts-node and the azure-devops-node-api package.

Let's create our app:

mkdir pull-request-preview
cd pull-request-preview
npm init --yes
npm install @types/node @types/yargs ts-node typescript azure-devops-node-api yargs --save

We'll update our newly created package.json file with a pull-request-preview script which will be the entry point.

  "scripts": {
"pull-request-preview": "ts-node ./index.ts"
},

We'll add a tsconfig.json file that looks like this:

{
"compilerOptions": {
"target": "ES2015",
"module": "CommonJS",
"strict": true,
"esModuleInterop": true,
"moduleResolution": "node"
}
}

Finally we'll add our script in a new index.ts file:

#!/usr/bin/env node
import yargs from 'yargs/yargs';
import * as nodeApi from 'azure-devops-node-api';
import { IGitApi } from 'azure-devops-node-api/GitApi';
import { PullRequestStatus } from 'azure-devops-node-api/interfaces/GitInterfaces';

const parser = yargs(process.argv.slice(2)).options({
pat: { type: 'string', default: '' },
sat: { type: 'string', default: '' },
systemCollectionUri: { type: 'string', demandOption: true },
project: { type: 'string', demandOption: true },
repository: { type: 'string', demandOption: true },
pullRequestId: { type: 'number' },
previewUrl: { type: 'string', demandOption: true },
});

(async () => {
await run(await parser.argv);
})();

async function run({
pat,
sat,
project,
repository,
systemCollectionUri,
pullRequestId,
previewUrl,
}: {
pat: string;
sat: string;
systemCollectionUri: string;
project: string;
repository: string;
pullRequestId: number | undefined;
previewUrl: string;
}) {
const config: Config = { project, repository };
const gitApi = await getGitApi({ pat, sat, systemCollectionUri });

if (!pullRequestId)
console.log(
'No pull request id supplied, so will look up latest active PR'
);

const pullRequestIdToUpdate =
pullRequestId || (await getActivePullRequestId({ gitApi, config }));
if (!pullRequestIdToUpdate) {
console.log('No pull request found');
return;
}

console.log(
`Updating ${systemCollectionUri}/${project}/_git/${repository}/pullrequest/${pullRequestIdToUpdate} with a preview URL of ${previewUrl}`
);

const pullRequest = await getPullRequest({
gitApi,
config,
pullRequestId: pullRequestIdToUpdate,
});

await updatePullRequestDescription({
gitApi,
config,
pullRequestId: pullRequestIdToUpdate,
description: makePreviewDescriptionMarkdown(
pullRequest.description!,
previewUrl
),
});

console.log(
`Updated pull request description a preview URL of ${previewUrl}`
);
}

interface Config {
project: string;
repository: string;
}

async function getGitApi({
sat,
pat,
systemCollectionUri,
}: {
pat: string;
sat: string;
systemCollectionUri: string;
}) {
const authHandler = pat
? nodeApi.getPersonalAccessTokenHandler(
pat,
/** allowCrossOriginAuthentication */ true
)
: nodeApi.getHandlerFromToken(
sat,
/** allowCrossOriginAuthentication */ true
);

const webApi = new nodeApi.WebApi(systemCollectionUri, authHandler);
const gitApi = await webApi.getGitApi();

return gitApi;
}

async function getActivePullRequestId({
gitApi,
config,
}: {
gitApi: IGitApi;
config: Config;
}) {
const topActivePullRequest = await gitApi.getPullRequests(
config.repository, // repository.id!,
{ status: PullRequestStatus.Active },
config.project,
undefined,
/** skip */ 0,
/** top */ 1
);

return topActivePullRequest.length > 0
? topActivePullRequest[0].pullRequestId
: undefined;
}

async function getPullRequest({
gitApi,
config,
pullRequestId,
}: {
gitApi: IGitApi;
config: Config;
pullRequestId: number;
}) {
const pullRequest = await gitApi.getPullRequest(
config.repository, // repository.id!,
pullRequestId,
config.project,
undefined,
/** skip */ 0,
/** top */ 1,
/** includeCommits */ false,
/** includeWorkItemRefs */ false
);
return pullRequest;
}

async function updatePullRequestDescription({
gitApi,
config,
pullRequestId,
description,
}: {
gitApi: IGitApi;
config: Config;
pullRequestId: number;
description: string;
}) {
// To do an update with the API you must provide a new object with only the properties you are updating
const updatePullRequest = {
description,
};
await gitApi.updatePullRequest(
updatePullRequest,
config.repository,
pullRequestId,
config.project
);
}

function makePreviewDescriptionMarkdown(desc: string, previewUrl: string) {
const previewRegex = /(> -*\n> # Preview:\n.*\n>.*\n> -*\n)/;

const makePreview = (previewUrl: string) => `> ---
> # Preview:
> ${previewUrl}
>
> ---
`;

const alreadyHasPreview = desc.match(previewRegex);
return alreadyHasPreview
? desc.replace(previewRegex, makePreview(previewUrl))
: makePreview(previewUrl) + desc;
}

The above code does two things:

  1. Looks up the pull request, using the details supplied from the pipeline. It's worth noting that the System.PullRequest.PullRequestId variable is initialized only if the build ran because of a Git PR affected by a branch policy. If you don't have that set up, the script falls back to using the latest active pull request. This is generally useful when you're getting set up in the first place; you won't want to rely on this behaviour.
  2. Updates the pull request description with a prefix piece of markdown that provides the link to the preview URL. This is our "browse the preview": screenshot of rendered markdown with the preview link

This script could be refactored into a dedicated Azure Pipelines custom task.

Permissions

The first time you run this you may encounter a permissions error of the form:

Error: TF401027: You need the Git 'PullRequestContribute' permission to perform this action.

To remedy this you need to give your build service the relevant permissions to update a pull request. You can do that by going to the security settings of your repo and setting "Contribute to pull requests" to "Allow" for your build service:

Screenshot of "Contribute to pull requests" permission in Azure DevOps Git security being set to "Allow"

Enjoy! (and keep Azure tidy)

When the pipeline is now run you can see that a deployment preview link is now updated onto the PR description:

Screenshot of deployment preview on PR

This will happen whenever a PR is raised which is tremendous.

A thing to remember, is that there's nothing in this post that tears down the temporary deployment after the pull request has been merged. It will hang around. We happen to be using free resources in this post, but if we weren't there would be cost implications. Either way, you'll want to clean up unused environments as a matter of course. And I'd advise automating that.

So be tidy and cost aware with this approach.