GitHub Actions - Building a Simple Bicep Workflow for Resource Deployment

In the previous article, we explored deploying Azure resources using Bicep with Azure DevOps. This week, we’re switching gears to GitHub Actions, showcasing a simple workflow to automate Azure deployments.

The following is a preview of the content covered in this article:

• Setting up a CI/CD workflow with a YAML file on GitHub.
• Manual workflow activation, along with a breakdown of its components.
• Common execution issues are being tackled to ensure a smooth deployment process.

In this article, I will provide you with the necessary information to use GitHub Actions for your Azure deployments with Bicep. This will help you to add a new tool to your DevOps toolkit.

Prerequisites #

To get started with our workflow in GitHub Actions, make sure you have completed the following prerequisites:

• GitHub Account: You will need a GitHub account to create and manage your workflow.
• Azure Subscription: Ensure you have an active Azure subscription to deploy the resources.
• Service principal: You must create a Service Principal and configure its permissions to allow GitHub Actions to interact with your Azure resources.

Workflow Overview #

Before delving into the details, it’s important to have an overall view of the complete workflow structure. Here is the full code of the workflow.

name: Deploy Azure Resources

on:
  push:
    branches:
      - main
    paths-ignore:
      - '*.md'
      - 'docs/*'
  workflow_dispatch:

env:
  AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}
  RESOURCE_GROUP_NAME: 'your-resource-group'
  TEMPLATE_FILE_PATH: './your-path/template.bicep'
  PARAMETERS_FILE_PATH: './your-path/parameters.json'

jobs:
  validate_and_preview:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

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

    - name: Validate Bicep files
      run: |
        az deployment group validate \
          --resource-group ${{ env.RESOURCE_GROUP_NAME }} \
          --template-file ${{ env.TEMPLATE_FILE_PATH }} \
          --parameters ${{ env.PARAMETERS_FILE_PATH }}        

    - name: What-if Bicep files
      run: |
        az deployment group what-if \
          --resource-group ${{ env.RESOURCE_GROUP_NAME }} \
          --template-file ${{ env.TEMPLATE_FILE_PATH }} \
          --parameters ${{ env.PARAMETERS_FILE_PATH }}        

  deploy_resources:
    needs: validate_and_preview
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

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

    - name: Deploy
      run: |
        az deployment group create \
          --resource-group ${{ env.RESOURCE_GROUP_NAME }} \
          --template-file ${{ env.TEMPLATE_FILE_PATH }} \
          --parameters ${{ env.PARAMETERS_FILE_PATH }}        

In this workflow, we have two main jobs. The first job is to validate the Bicep files to ensure there are no issues during deployment. The second job is the actual deployment of Azure resources if validation is successful. In the following sections, we will analyze each component of this workflow and explain its purpose and function in detail.

Workflow Breakdown #

In this section, we will explore the fundamental elements that comprise a GitHub Actions workflow configuration file.

Name Declaration #

This defines the name of the workflow which will appear in the Actions tab of the GitHub repository.

name: Deploy Azure Resources  

Triggers #

The workflow will be triggered on push events to the main branch, excluding pushes that only change markdown files or files within the docs directory. workflow_dispatch allows for manual triggering of the workflow through the GitHub UI.

on:
  push:
    branches:
      - main
    paths-ignore:
      - '*.md'
      - 'docs/*'
  workflow_dispatch:

Environment Variables #

Defining environment variables that will be used across jobs in the workflow.

env:
  AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}
  RESOURCE_GROUP_NAME: 'your-resource-group'
  TEMPLATE_FILE_PATH: './your-path/template.bicep'
  PARAMETERS_FILE_PATH: './your-path/parameters.json'

Secrets These are encrypted environment variables established within the repository settings. They serve as secure storage for sensitive information, such as API keys or credentials, which should not be disclosed within your workflow file.

The expression secrets.AZURE_CREDENTIALS securely references the AZURE_CREDENTIALS secret configured in the repository settings.

This expression allows the azure/login@v1 action to authenticate to Azure securely, thus enabling subsequent steps that deploy resources to Azure.

Usage of Environment Variables

The TEMPLATE_FILE_PATH and PARAMETERS_FILE_PATH environment variables are used to specify the file paths for the Bicep template and its parameters file respectively.

By defining these as environment variables, you can easily manage and modify the file paths in one central location at the workflow level, ensuring consistency across all jobs and steps within the workflow.

Jobs #

The workflow contains two main jobs: validate_and_preview and deploy_resources.

jobs:
  validate_and_preview:
    runs-on: ubuntu-latest
    steps:
    ... 

  deploy_resources:
    needs: validate_and_preview
    runs-on: ubuntu-latest
    steps:
    ...

validate_and_preview: This job validates Bicep files and runs a what-if operation to preview potential resource changes.

deploy_resources: This job is dependent on the success of validate_and_preview, as indicated by needs: validate_and_preview. If the validation and preview are successful, it proceeds to deploy the resources to Azure.

Runners #

The runs-on keyword specifies the type of machine to run the job on. In this workflow, both jobs are configured to run on the latest version of Ubuntu virtual machine provided by GitHub, this indicated by runs-on: ubuntu-latest. GitHub offers different runners, such as Ubuntu, Windows, and macOS, each with specific versions. Depending on your workflow requirements, you can select a specific runner and version..

Steps #

Each job contains a series of steps to run commands, run scripts, or use GitHub Actions from the marketplace, such as actions/checkout@v4 and azure/login@v1.

Execution Commands: #

Within the steps, you’ll find command-line instructions to validate, preview, and deploy resources using Azure CLI commands.

Building Your CI/CD Workflow #

1- Access Your GitHub Repository: Navigate to your GitHub repository and select Actions from the top menu.

2- Initiate a New Workflow:

• Click on New workflow.
• Choose to set up a workflow yourself.

3- Naming Your Workflow File:

• You may want to rename the workflow file to something more descriptive, like GitHubActions_BicepDeployment_Simple.yml.

4- Uploading Your Workflow File:

• If you already have a workflow file created on your local machine (as per the earlier steps), you can upload it here. Alternatively, replace the content of the existing .yml file with the workflow code.

5- Organizing Your Workflow File:

• Place the GitHubActions_BicepDeployment_Simple.yml file in the .github/workflows/ directory of your repository.

6- Executing Your Workflow:

• Once uploaded, the workflow will be listed in the Actions tab within your project.
• You can trigger the workflow manually by selecting it and then clicking on Run workflow, or it will trigger automatically based on the conditions defined in the on section of the YAML file.

7- Monitoring Your Workflow:

• Navigate to the Actions tab in your GitHub repository to monitor the status of your workflow runs. Here, you can see the progress, review logs, and troubleshoot if necessary.

Common Issues and Troubleshooting #

Deploying Azure resources through a workflow can still be challenging, even with careful planning. It is common to face unexpected issues. Here, I will discuss common problems and their solutions.

Workflow Not Triggering #

• Symptom: Despite making changes to branches other than main, the workflow doesn’t start.
• Solution: Ensure that the YAML file is correctly placed in the .github/workflows/ directory of your repository and that the branch protection rules don’t prevent the workflow from triggering. Also, verify the trigger configuration in your YAML file.

Authentication Failure #

• Symptom: The workflow fails during the Azure login step, indicating authentication issues.
• Solution: Verify that the AZURE_CREDENTIALS secret has been correctly set up in your GitHub repository settings. Ensure that the service principal associated with the AZURE_CREDENTIALS secret has the necessary permissions in Azure. For more information, check out this link.

Resource Deployment Failure #

• Symptom: The deployment step fails, indicating issues with deploying resources to Azure.
• Solution: Review the error message provided in the GitHub Actions log. Check the resource configurations and parameters in your Bicep files. Verify that the Azure subscription and resource group are correctly specified.

Manual Trigger Not Working #

• Symptom: Unable to manually trigger the workflow from the GitHub Actions interface.
• Solution: Ensure that the workflow YAML file is correctly formatted and located in the .github/workflows/ directory of your repository. Verify that the manual trigger conditions in the on section of the YAML file are correctly defined.

Validation Failure #

• Symptom: The validation step fails, indicating errors in the Bicep files.
• Solution: Review the error message provided in the GitHub Actions log. Check the syntax and contents of your Bicep files for errors. Validate your Bicep files locally using the Azure CLI.

References and useful links #

• Official Bicep Documentation
• Official GitHub Actions Documentation

Thank you for taking the time to read my post. I sincerely hope that you find it helpful.