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!

How to reference the current branch in GitHub Actions

How to use the branch name in a job