Use GitHub Actions to connect to Azure

Learn how to use Azure login with either Azure PowerShell or Azure CLI to interact with your Azure resources.

To use Azure PowerShell or Azure CLI in a GitHub Actions workflow, you need to first log in with the Azure login action.

The Azure login action supports two different ways of authenticating with Azure:

• Service principal with secrets
• OpenID Connect (OIDC) with a Azure service principal using a Federated Identity Credential

By default, the login action logs in with the Azure CLI and sets up the GitHub Actions runner environment for Azure CLI. You can use Azure PowerShell with enable-AzPSSession property of the Azure login action. This sets up the GitHub Actions runner environment with the Azure PowerShell module.

You can use Azure login to connect to public or sovereign clouds including Azure Government and Azure Stack Hub.

Use the Azure login action with OpenID Connect

To set up an Azure Login with OpenID Connect and use it in a GitHub Actions workflow, you'll need:

• An Azure Active Directory application, with a service principal that has been assigned with an appropriate role to your subscription.
• An Azure Active Directory application configured with a federated credential to trust tokens issued by GitHub Actions to your GitHub repository. You can configure this in the Azure portal or with Microsoft Graph REST APIs.
• A GitHub Actions workflow that requests GitHub issue tokens to the workflow, and uses the Azure login action.

Create an Azure Active Directory application and service principal

You'll need to create an Azure Active Directory application and service principal and then assign a role on your subscription to your application so that your workflow has access to your subscription.

Azure portal

1. If you do not have an existing application, register a new Azure Active Directory application and service principal that can access resources. As part of this process, make sure to:

   • Register your application with Azure AD and create a service principal
   • Assign a role to the application

2. Open App registrations in Azure portal and find your application. Copy the values for Application (client) ID and Directory (tenant) ID to use in your GitHub Actions workflow.

3. Open Subscriptions in Azure portal and find your subscription. Copy the Subscription ID.

Azure CLI

1. Create the Azure Active Directory application.

   az ad app create --display-name myApp
   

   This command will output JSON with an appId that is your client-id. The objectId is APPLICATION-OBJECT-ID and it will be used for creating federated credentials with Graph API calls.

2. Create a service principal. Replace the $appID with the appId from your JSON output. This command generates JSON output with a different objectId will be used in the next step. The new objectId is the assignee-object-id.

    az ad sp create --id $appId
   

3. 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 generated assignee-object-id (the newly created service principal object id).

   az role assignment create --role contributor --subscription $subscriptionId --assignee-object-id  $assigneeObjectId --assignee-principal-type ServicePrincipal --scope /subscriptions/$subscriptionId/resourceGroups/$resourceGroupName
   

4. Copy the values for clientId, subscriptionId, and tenantId to use later in your GitHub Actions workflow.

Azure PowerShell

1. Create the Azure Active Directory application.

   New-AzADApplication -DisplayName myApp
   

   This command will output the AppId property that is your ClientId. The Id property is APPLICATION-OBJECT-ID and it will be used for creating federated credentials with Graph API calls.

2. Create a service principal. Replace the $clientId with the AppId from your output. This command generates output with a different Id and will be used in the next step. The new Id is the ObjectId.

   $clientId = (Get-AzADApplication -DisplayName myApp).AppId
   New-AzADServicePrincipal -ApplicationId $clientId
   

3. Create a new role assignment. Beginning with Az PowerShell module version 7.x, New-AzADServicePrincipal no longer assigns the Contributor role to the service principal by default. Replace $resourceGroupName with your resource group name, and $objectId with generated Id.

   $objectId = (Get-AzADServicePrincipal -DisplayName myApp).Id
   New-AzRoleAssignment -ObjectId $objectId -RoleDefinitionName Contributor -ResourceGroupName $resourceGroupName
   

4. Get the values for clientId, subscriptionId, and tenantId to use later in your GitHub Actions workflow.

   $clientId = (Get-AzADApplication -DisplayName myApp).AppId
   $subscriptionId = (Get-AzContext).Subscription.Id
   $tenantId = (Get-AzContext).Subscription.TenantId
   

Add federated credentials

You can add federated credentials in the Azure portal or with the Microsoft Graph REST API.

Azure portal

1. Go to App registrations in the Azure portal and open the app you want to configure.
2. Within the app, go to Certificates and secrets.
   
3. In the Federated credentials tab, select Add credential.
4. Select the credential scenario GitHub Actions deploying Azure resources. Generate your credential by entering your credential details.

Field	Description	Example
Organization	Your GitHub organization name or GitHub username.	contoso
Repository	Your GitHub Repository name.	contoso-app
Entity type	The filter used to scope the OIDC requests from GitHub workflows. This field is used to generate the subject claim.	Environment, Branch, Pull request, Tag
GitHub name	The name of the environment, branch, or tag.	main
Name	Identifier for the federated credential.	contoso-deploy

For a more detailed overview, see Configure an app to trust a GitHub repo.

Azure CLI

Run the following command to create a new federated identity credential for your Azure Active Directory application.

• Replace APPLICATION-OBJECT-ID with the objectId (generated while creating app) for your Azure 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 ad app federated-credential create --id <APPLICATION-OBJECT-ID> --parameters credential.json
("credential.json" contains the following content)
{
    "name": "<CREDENTIAL-NAME>",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:octo-org/octo-repo:environment:Production",
    "description": "Testing",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

For a more detailed overview, see Configure an app to trust an external identity provider.

Azure PowerShell

Run New-AzADAppFederatedCredential cmdlet to create a new federated identity credential for your Azure Active Directory application.

• Replace APPLICATION-OBJECT-ID with the Id (generated while creating app) for your Azure 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.

New-AzADAppFederatedCredential -ApplicationObjectId APPLICATION-OBJECT-ID -Audience api://AzureADTokenExchange -Issuer 'https://token.actions.githubusercontent.com/' -Name 'GitHub-Actions-Test' -Subject 'repo:octo-org/octo-repo:environment:Production'

For a more detailed overview, see Configure an app to trust a GitHub repo.

Create GitHub secrets

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.

1. Open your GitHub repository and go to Settings.

   

2. Select Security > Secrets and variables > Actions.

   

3. Create secrets for AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID. Use these values from your Azure Active Directory application for your GitHub secrets:

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

4. Save each secret by selecting Add secret.

Set up Azure Login with OpenID Connect authentication

Your GitHub Actions workflow uses OpenID Connect to authenticate with Azure. To learn more about this interaction, see the GitHub Actions documentation.

In this example, you'll use OpenID Connect Azure CLI to authenticate with Azure with the Azure login action. The example uses GitHub secrets for the client-id, tenant-id, and subscription-id values. You can also pass these values directly in the login action.

The Azure login action includes an optional audience input parameter that defaults to api://AzureADTokenExchange. You can update this parameter for custom audience values.

Linux

This workflow authenticates with OpenID Connect and uses Azure CLI to get the details of the connected subscription and list resource group.

name: Run Azure Login with OpenID Connect
on: [push]

permissions:
      id-token: write
      contents: read
      
jobs: 
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: 'Az CLI login'
      uses: azure/login@v1
      with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
  
    - name: 'Run Azure CLI commands'
      run: |
          az account show
          az group list
          pwd 

Windows

This workflow authenticates with OpenID Connect and uses PowerShell to output a list of resource groups tied to the connected Azure subscription.

name: Run Azure Login with OpenID Connect and PowerShell
on: [push]

permissions:
      id-token: write
      contents: read
      
jobs: 
  Windows-latest:
      runs-on: windows-latest
      steps:
        - name: OIDC Login to Azure Public Cloud with AzPowershell (enableAzPSSession true)
          uses: azure/login@v1
          with:
            client-id: ${{ secrets.AZURE_CLIENT_ID }}
            tenant-id: ${{ secrets.AZURE_TENANT_ID }}
            subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} 
            enable-AzPSSession: true

        - name: 'Get resource group with PowerShell action'
          uses: azure/powershell@v1
          with:
             inlineScript: |
               Get-AzResourceGroup
             azPSVersion: "latest"

Verify successful Azure Login with OpenID

Open the Az CLI login action and verify that it ran successfully. You should see the message Login successful. If your login is unsuccessful, you'll see the message Az CLI Login failed..

Use the Azure login action with a service principal secret

To use Azure login with a service principal, you first need to add your Azure service principal as a secret to your GitHub repository.

Create a service principal

In this example, you will create a secret named AZURE_CREDENTIALS that you can use to authenticate with Azure.

1. Open Azure Cloud Shell in the Azure portal or Azure CLI locally.

   Note

   If you are using Azure Stack Hub, you'll need to set your SQL Management endpoint to not supported. az cloud update -n {environmentName} --endpoint-sql-management https://notsupported

2. Create a new service principal in the Azure portal for your app. The service principal must be assigned with an appropriate role.

       az ad sp create-for-rbac --name "myApp" --role contributor \
                                   --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group} \
                                   --json-auth
   

   The parameter --json-auth outputs the result dictionary accepted by the login action, accessible in Azure CLI versions >= 2.51.0. Versions prior to this use --sdk-auth with a deprecation warning.

3. Copy the JSON object for your service principal.

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

Add the service principal as a GitHub secret

1. In GitHub, go to your repository.

2. Go to Settings in the navigation menu.

3. Select Security > Secrets and variables > Actions.

   

4. Select New repository secret.

5. Paste the entire JSON output from the Azure CLI command into the secret's value field. Give the secret the name AZURE_CREDENTIALS.

6. Select Add secret.

Use the Azure login action

Use the service principal secret with the Azure Login action to authenticate to Azure.

In this workflow, you authenticate using the Azure login action with the service principal details stored in secrets.AZURE_CREDENTIALS. Then, you run an Azure CLI action. For more information about referencing GitHub secrets in a workflow file, see Using encrypted secrets in a workflow in GitHub Docs.

Once you have a working Azure login step, you can use the Azure PowerShell or Azure CLI actions. You can also use other Azure actions, like Azure webapp deploy and Azure functions.

on: [push]

name: AzureLoginSample

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Log in with Azure
        uses: azure/login@v1
        with:
          creds: '${{ secrets.AZURE_CREDENTIALS }}'

Use the Azure PowerShell action

In this example, you log in with the Azure Login action and then retrieve a resource group with the Azure PowerShell action.

on: [push]

name: AzureLoginSample

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Log in with Azure
        uses: azure/login@v1
        with:
          creds: '${{ secrets.AZURE_CREDENTIALS }}'
          enable-AzPSSession: true
      - name: Azure PowerShell Action
        uses: Azure/powershell@v1
        with:
          inlineScript: Get-AzResourceGroup -Name "< YOUR RESOURCE GROUP >"
          azPSVersion: "latest"

Use the Azure CLI action

In this example, you log in with the Azure Login action and then retrieve a resource group with the Azure CLI action.

on: [push]

name: AzureLoginSample

jobs:
build-and-deploy:
    runs-on: ubuntu-latest
    steps:

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

    - name: Azure CLI script
        uses: azure/CLI@v1
        with:
        azcliversion: 2.0.72
        inlineScript: |
            az account show
            az storage -h

Connect to Azure Government and Azure Stack Hub clouds

To log in to one of the Azure Government clouds, set the optional parameter environment with supported cloud names AzureUSGovernment or AzureChinaCloud. If this parameter is not specified, it takes the default value AzureCloud and connects to the Azure Public Cloud.

   - name: Login to Azure US Gov Cloud with CLI
     uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_US_GOV_CREDENTIALS }}
          environment: 'AzureUSGovernment'
          enable-AzPSSession: false
   - name: Login to Azure US Gov Cloud with Az Powershell
      uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_US_GOV_CREDENTIALS }}
          environment: 'AzureUSGovernment'
          enable-AzPSSession: true

Connect with other Azure services

The following articles provide details on connecting to GitHub from Azure and other services.

Azure Active Directory

• Sign in to GitHub Enterprise with Azure AD (single sign-on)

Power BI

• Connect Power BI with GitHub

Connectors

• GitHub connector for Azure Logic Apps, Power Automate and Power Apps

Azure Databricks

• Use GitHub as version control for notebooks

Deploy apps from GitHub to Azure