Deploy ARM templates by using GitHub Actions

Article
10/09/2024

GitHub Actions is a suite of features in GitHub to automate your software development workflows in the same place you store code and collaborate on pull requests and issues.

Use the Deploy Azure Resource Manager Template Action to automate deploying an Azure Resource Manager template (ARM template) to Azure.

Prerequisites

An Azure account with an active subscription. Create a trial subscription.
A GitHub account. If you don't have one, sign up for free.
- A GitHub repository to store your Resource Manager templates and your workflow files. To create one, see Creating a new repository.

Workflow file overview

A workflow is defined by a YAML (.yml) file in the /.github/workflows/ path in your repository. This definition contains the various steps and parameters that make up the workflow.

The file has two sections:

Section	Tasks
Authentication	1. Generate deployment credentials.
Deploy	1. Deploy the Resource Manager template.

You can create a service principal with the az ad sp create-for-rbac command in the Azure CLI.

Create a resource group if you do not already have one.

    az group create -n {MyResourceGroup} -l {location}

Replace the placeholder myApp with the name of your application.

   az ad sp create-for-rbac --name {myApp} --role contributor --scopes /subscriptions/{subscription-id}/resourceGroups/{MyResourceGroup} --sdk-auth

In the example above, replace the placeholders with your subscription ID and resource group name. The output is a JSON object with the role assignment credentials that provide access to your App Service app similar to below. Copy this JSON object for later. You will only need the sections with the clientId, clientSecret, subscriptionId, and tenantId values.

  {
    "clientId": "<GUID>",
    "clientSecret": "<GUID>",
    "subscriptionId": "<GUID>",
    "tenantId": "<GUID>",
    (...)
  }

Important

It is always a good practice to grant minimum access. The scope in the previous example is limited to the resource group.

OpenID Connect is an authentication method that uses short-lived tokens. Setting up OpenID Connect with GitHub Actions is more complex process that offers hardened security.

If you do not have an existing application, register a new Active Directory application and service principal that can access resources. Create the Active Directory application.
```
az ad app create --display-name myApp
```
This command will output JSON with an appId that is your client-id. Save the value to use as the AZURE_CLIENT_ID GitHub secret later.

You'll use the objectId value when creating federated credentials with Graph API and reference it as the APPLICATION-OBJECT-ID.
Create a service principal. Replace the $appID with the appId from your JSON output.

This command generates JSON output with a different objectId and will be used in the next step. The new objectId is the assignee-object-id.

Copy the appOwnerTenantId to use as a GitHub secret for AZURE_TENANT_ID later.
```
 az ad sp create --id $appId
```
Create a new role assignment by subscription and object. By default, the role assignment will be tied to your default subscription. Replace $subscriptionId with your subscription ID, $resourceGroupName with your resource group name, and $assigneeObjectId with the generated assignee-object-id. Learn how to manage Azure subscriptions with the Azure CLI.
```
az role assignment create --role contributor --subscription $subscriptionId --assignee-object-id  $assigneeObjectId --assignee-principal-type ServicePrincipal --scopes /subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.Web/sites/
```
Run the following command to create a new federated identity credential for your active directory application.
- Replace APPLICATION-OBJECT-ID with the objectId (generated while creating app) for your Active Directory application.
- Set a value for CREDENTIAL-NAME to reference later.
- Set the subject. The value of this is defined by GitHub depending on your workflow:
  - Jobs in your GitHub Actions environment: repo:< Organization/Repository >:environment:< Name >
  - For Jobs not tied to an environment, include the ref path for branch/tag based on the ref path used for triggering the workflow: repo:< Organization/Repository >:ref:< ref path>. For example, repo:n-username/ node_express:ref:refs/heads/my-branch or repo:n-username/ node_express:ref:refs/tags/my-tag.
  - For workflows triggered by a pull request event: repo:< Organization/Repository >:pull_request.
```
az rest --method POST --uri 'https://microsoftgraph.chinacloudapi.cn/beta/applications/<APPLICATION-OBJECT-ID>/federatedIdentityCredentials' --body '{"name":"<CREDENTIAL-NAME>","issuer":"https://token.actions.githubusercontent.com","subject":"repo:organization/repository:ref:refs/heads/main","description":"Testing","audiences":["api://AzureADTokenExchange"]}' 
```

Configure the GitHub secrets

Service principal
OpenID Connect

You need to create secrets for your Azure credentials, resource group, and subscriptions.

In GitHub, browse your repository.
Select Settings > Secrets > New secret.
Paste the entire JSON output from the Azure CLI command into the secret's value field. Give the secret the name AZURE_CREDENTIALS.
Create another secret named AZURE_RG. Add the name of your resource group to the secret's value field (example: myResourceGroup).
Create an additional secret named AZURE_SUBSCRIPTION. Add your subscription ID to the secret's value field (example: 90fd3f9d-4c61-432d-99ba-1273f236afa2).

You need to provide your application's Client ID, Tenant ID, and Subscription ID to the login action. These values can either be provided directly in the workflow or can be stored in GitHub secrets and referenced in your workflow. Saving the values as GitHub secrets is the more secure option.

Open your GitHub repository and go to Settings.
Select Settings > Secrets > New secret.
Create secrets for AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID. Use these values from your Active Directory application for your GitHub secrets:

GitHub Secret Active Directory Application

AZURE_CLIENT_ID Application (client) ID

AZURE_TENANT_ID Directory (tenant) ID

AZURE_SUBSCRIPTION_ID Subscription ID
Save each secret by selecting Add secret.

GitHub Secret	Active Directory Application
AZURE_CLIENT_ID	Application (client) ID
AZURE_TENANT_ID	Directory (tenant) ID
AZURE_SUBSCRIPTION_ID	Subscription ID

Add Resource Manager template

Add a Resource Manager template to your GitHub repository. This template creates a storage account.

https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json

You can put the file anywhere in the repository. The workflow sample in the next section assumes the template file is named azuredeploy.json, and it's stored at the root of your repository.

Create workflow

The workflow file must be stored in the .github/workflows folder at the root of your repository. The workflow file extension can be either .yml or .yaml.

From your GitHub repository, select Actions from the top menu.
Select New workflow.
Select set up a workflow yourself.
Rename the workflow file if you prefer a different name other than main.yml. For example: deployStorageAccount.yml.
Replace the content of the yml file with the following:

Service principal
OpenID Connect

  on: [push]
  name: Azure ARM
  jobs:
    build-and-deploy:
      runs-on: ubuntu-latest
      steps:

        # Checkout code
      - uses: actions/checkout@main

        # Log into Azure
      - uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

        # Deploy ARM template
      - name: Run ARM deploy
        uses: azure/arm-deploy@v1
        with:
          subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION }}
          resourceGroupName: ${{ secrets.AZURE_RG }}
          template: ./azuredeploy.json
          parameters: storageAccountType=Standard_LRS

        # output containerName variable from template
      - run: echo ${{ steps.deploy.outputs.containerName }}

Note

You can specify a JSON format parameters file instead in the ARM Deploy action (example: .azuredeploy.parameters.json).

The first section of the workflow file includes:

name: The name of the workflow.
on: The name of the GitHub events that triggers the workflow. The workflow is trigger when there's a push event on the main branch, which modifies at least one of the two files specified. The two files are the workflow file and the template file.

  on: [push]
  name: Azure ARM
  jobs:
    build-and-deploy:
      runs-on: ubuntu-latest
      steps:

        # Checkout code
      - uses: actions/checkout@main

        # Log into Azure
      - uses: azure/login@v1
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

        # Deploy ARM template
      - name: Run ARM deploy
        uses: azure/arm-deploy@v1
        with:
          subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION }}
          resourceGroupName: ${{ secrets.AZURE_RG }}
          template: ./azuredeploy.json
          parameters: storageAccountType=Standard_LRS

        # output containerName variable from template
      - run: echo ${{ steps.deploy.outputs.containerName }}

Note

You can specify a JSON format parameters file instead in the ARM Deploy action (example: .azuredeploy.parameters.json).

The first section of the workflow file includes:

name: The name of the workflow.
on: The name of the GitHub events that triggers the workflow. The workflow is trigger when there's a push event on the main branch, which modifies at least one of the two files specified. The two files are the workflow file and the template file.

Select Start commit.
Select Commit directly to the main branch.
Select Commit new file (or Commit changes).

Because the workflow is configured to be triggered by either the workflow file or the template file being updated, the workflow starts right after you commit the changes.

Check workflow status

Select the Actions tab. You see a Create deployStorageAccount.yml workflow listed. It takes 1-2 minutes to run the workflow.
Select the workflow to open it.
Select Run ARM deploy from the menu to verify the deployment.

Clean up resources

When your resource group and repository are no longer needed, clean up the resources you deployed by deleting the resource group and your GitHub repository.

Next steps

Create your first ARM template