Build, test, and deploy containers to Azure Kubernetes Service (AKS) using GitHub Actions

GitHub Actions gives you the flexibility to build an automated software development lifecycle workflow. You can use multiple Kubernetes actions to deploy to containers from Azure Container Registry (ACR) to Azure Kubernetes Service (AKS) with GitHub Actions.


GitHub Actions for AKS

With GiHub Actions, you can automate your software development workflows from within GitHub. For more information, see GitHub Actions for Azure.

The following table lists the available actions for AKS:

Name Description More details
azure/aks-set-context Set the target AKS cluster context for other actions to use or run any kubectl commands. azure/aks-set-context
azure/k8s-set-context Set the target Kubernetes cluster context for other actions to use or run any kubectl commands. azure/k8s-set-context
azure/k8s-bake Bake manifest file to use for deployments using Helm, kustomize, or kompose. azure/k8s-bake
azure/k8s-create-secret Create a generic secret or docker-registry secret in the Kubernetes cluster. azure/k8s-create-secret
azure/k8s-deploy Deploy manifests to Kubernetes clusters. azure/k8s-deploy
azure/k8s-lint Validate/lint your manifest files. azure/k8s-lint
azure/setup-helm Install a specific version of Helm binary on the runner. azure/setup-helm
azure/setup-kubectl Install a specific version of kubectl on the runner. azure/setup-kubectl
azure/k8s-artifact-substitute Update the tag or digest for container images. azure/k8s-artifact-substitute
azure/aks-create-action Create an AKS cluster using Terraform. azure/aks-create-action
azure/aks-github-runner Set up self-hosted agents for GitHub Actions. azure/aks-github-runner
azure/acr-build Build containers using ACR. azure/acr-build

Use GitHub Actions with AKS

As an example, you can use GitHub Actions to deploy an application to your AKS cluster every time a change is pushed to your GitHub repository. This example uses the Azure Vote application.


This example uses a service principal for authentication with your ACR and AKS cluster. Alternatively, you can configure Open ID Connect (OIDC) and update the azure/login action to use OIDC. For more information, see Set up Azure Login with OpenID Connect authentication.

Fork and update the repository

  1. Navigate to the Azure Vote repository and select Fork.

  2. Update the azure-vote-all-in-one-redis.yaml to use your ACR for the azure-vote-front image. Replace <registryName> with the name of your registry.

          - name: azure-vote-front
            image: <registryName>
  3. Commit the updated azure-vote-all-in-one-redis.yaml to your repository.

Create secrets

  1. Create a service principal to access your resource group with the Contributor role using the az ad sp create-for-rbac command. Replace <SUBSCRIPTION_ID> with the subscription ID of your Azure account and <RESOURCE_GROUP> with the name of the resource group containing your ACR.

    az ad sp create-for-rbac \
        --name "ghActionAzureVote" \
        --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP> \
        --role Contributor \

    Your output should look similar to the following example output:

      "clientId": <clientId>,
      "clientSecret": <clientSecret>,
      "subscriptionId": <subscriptionId>,
      "tenantId": <tenantId>,
  2. Navigate to your GitHub repository settings and select Security > Secrets and variables > Actions.

  3. For each secret, select New Repository Secret and enter the name and value of the secret.

    Secret name Secret value
    AZURE_CREDENTIALS The entire JSON output from the az ad sp create-for-rbac command.
    service_principal The value of <clientId>.
    service_principal_password The value of <clientSecret>.
    subscription The value of <subscriptionId>.
    tenant The value of <tenantId>.
    registry The name of your registry.
    repository azuredocs
    resource_group The name of your resource group.
    cluster_name The name of your cluster.

For more information about creating secrets, see Encrypted Secrets.

Create actions file

  1. In your repository, create a .github/workflows/main.yml and paste in the following contents:

    name: build_deploy_aks
          - "azure-vote/**"
        runs-on: ubuntu-latest
          - name: Checkout source code 
            uses: actions/checkout@v3
          - name: ACR build
            id: build-push-acr
            uses: azure/acr-build@v1
              service_principal: ${{ secrets.service_principal }}
              service_principal_password: ${{ secrets.service_principal_password }}
              tenant: ${{ secrets.tenant }}
              registry: ${{ secrets.registry }}
              repository: ${{ secrets.repository }}
              image:  azure-vote-front
              folder: azure-vote
              branch: master
              tag: ${{ github.sha }}
          - name: Azure login
            id: login
            uses: azure/login@v1.4.3
              creds: ${{ secrets.AZURE_CREDENTIALS }}
          - name: Set AKS context
            id: set-context
            uses: azure/aks-set-context@v3
              resource-group: '${{ secrets.resource_group }}' 
              cluster-name: '${{ secrets.cluster_name }}'
          - name: Setup kubectl
            id: install-kubectl
            uses: azure/setup-kubectl@v3
          - name: Deploy to AKS
            id: deploy-aks
            uses: Azure/k8s-deploy@v4
              namespace: 'default'
              manifests: |
              images: '${{ secrets.registry }}${{ secrets.repository }}/azure-vote-front:${{ github.sha }}'
              pull-images: false 

    The on section contains the event that triggers the action. In the example file, the action triggers when a change is pushed to the azure-vote directory.

    The steps section contains each distinct action:

    1. Checkout source code uses the GitHub Actions Checkout Action to clone the repository.
    2. ACR build uses the Azure Container Registry Build Action to build the image and upload it to your registry.
    3. Azure login uses the Azure Login Action to sign in to your Azure account.
    4. Set AKS context uses the Azure AKS Set Context Action to set the context for your AKS cluster.
    5. Setup kubectl uses the Azure AKS Setup Kubectl Action to install kubectl on your runner.
    6. Deploy to AKS uses the Azure Kubernetes Deploy Action to deploy the application to your Kubernetes cluster.
  2. Commit the .github/workflows/main.yml file to your repository.

  3. To confirm the action is working, update the azure-vote/azure-vote/config_file.cfg with the following contents:

    # UI Configurations
    TITLE = 'Azure Voting App'
    VOTE1VALUE = 'Fish'
    VOTE2VALUE = 'Dogs'
    SHOWHOST = 'false'
  4. Commit the updated azure-vote/azure-vote/config_file.cfg to your repository.

  5. In your repository, select Actions and confirm a workflow is running. Then, confirm the workflow has a green checkmark and the updated application is deployed to your cluster.

Next steps

Review the following starter workflows for AKS. For more information, see Using starter workflows.