How to reference the current branch in GitHub Actions

When building deploy pipelines, referencing the name of the branch that a GitHub Actions workflow is running with can be useful.

I recently gave a talk on how platforms like Netlify build and deploy web applications using changes to GitHub branches. Part of the talk was a brief demonstration of how I built branch-based deployments into my SaaS.

The name of the current branch was passed into my deploy process using AWS SAM as a parameter to create resources in AWS unique to the name of the branch.

It’s rather straightforward with a simple bash step.

How to use the branch name in a job

Start by adding a step into the workflow that extracts the name of the branch from the workflow context and sets it on a job parameter:

- name: Extract branch name
  shell: bash
  # 👉 We're extracting the name of the branch and setting it to the
  # 'branch' variable in this step
  run: echo "branch=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT
  # 👉 The ID of the branch
  id: extract_branch

You can now reference the value throughout the remainder of the job like so:

- name: Build & deploy
  shell: bash
  working-directory: backend/stack
  env:
    GOOS: linux
    GOARCH: amd64
    CGO_ENABLED: 0
    # 👉 Notice how the ID of the previous step is referenced.
    SITE_ALIAS: ${{ steps.extract_branch.outputs.branch }}
  run: make deploy-branch

Here is the YAML for the entire workflow used in this example:

name: Deploy backend (QA)

on:
  workflow_dispatch:
  push:
    branches:
      - qa
    paths:
      - backend/**

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  AWS_DEFAULT_REGION: 'us-west-1'

jobs:
  deploy-backend:
    environment: ${{ github.ref_name == 'main' && 'production' || github.ref_name }}
    name: Deploy backend
    runs-on: ubuntu-latest
    steps:
      - name: Extract branch name
        shell: bash
        run: echo "branch=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT
        id: extract_branch
      - name: Checkout
        uses: actions/checkout@v3
      - uses: aws-actions/setup-sam@v2
        with:
          use-installer: true
      - name: Sam version
        run: |
          sam --version
      - name: Write default params.json file
        shell: bash
        working-directory: backend/stack
        run: |
          echo "${{ secrets.PARAMS_JSON_ENCODED }}" >> params.encoded
          base64 -d -i params.encoded >> params.json
          cat params.json
      - name: Transform configs
        shell: bash
        working-directory: scripts/transform-json
        env:
          SITE_ALIAS: ${{ steps.extract_branch.outputs.branch }}
          BUNGIE_API_KEY: ${{ secrets.BUNGIE_API_KEY }}
          CERT_ARN: ${{ secrets.CERT_ARN }}
          DISCORD_FEEDBACK_WEBHOOK: ${{ secrets.DISCORD_FEEDBACK_WEBHOOK }}
          OAUTH_CLIENT_ID: ${{ secrets.OAUTH_CLIENT_ID }}
          OAUTH_CLIENT_SECRET: ${{ secrets.OAUTH_CLIENT_SECRET }}
          STRIPE_ERROR_CB: ${{ secrets.STRIPE_ERROR_CB }}
          STRIPE_KEY: ${{ secrets.STRIPE_KEY }}
          STRIPE_SUCCESS_CB: ${{ secrets.STRIPE_SUCCESS_CB }}
          STRIPE_WEBHOOK_KEY: ${{ secrets.STRIPE_WEBHOOK_KEY }}
        run: |
          go run main.go \
            --mapfile ../../backend/stack/transform_map.json \
            --configfile ../../backend/stack/params.json
          cat ../../backend/stack/params.json
      - name: Build & deploy
        shell: bash
        working-directory: backend/stack
        env:
          GOOS: linux
          GOARCH: amd64
          CGO_ENABLED: 0
          SITE_ALIAS: ${{ steps.extract_branch.outputs.branch }}
        run: make deploy-branch

All of this code is open source as well if you’d rather read it directly on GitHub: https://github.com/GuardianForge/guardianforge.net/blob/main/.github/workflows/deploy-backend-qa.yaml

🤗 If you are interested in more content like this and want to support me, consider joining my newsletter!