How to Use Git Tags for Auto Deployment with GitHub Actions on Heroku

For an introduction to git tags and how to create them, please refer to my previous blog post: Releasing & Versioning of Software.

In this guide, we'll explore how to automatically deploy an application on Heroku based on the tags or versions assigned to your commits in git.

Setting Up the Workflow

To create a workflow file for this process, start by creating a `.github/workflows` folder structure in the root directory of your project, as shown in the figure on the right.

Name the file `github-actions-heroku-dev.yml` or something of your choice, the file must have '.yml' extension and place it inside the folder structure. Here is a sample content of the file:

name: Deploy to Heroku on Tag Push

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Install Heroku CLI
    run: curl https://cli-assets.heroku.com/install.sh | sh

    - name: Login to Heroku
    env:
      HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
    run: heroku container:login

    - name: Deploy to Heroku
    env:
      HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
      HEROKU_APP_NAME: ${{ secrets.HEROKU_APP_NAME }}
    run: |
      git push https://heroku:$HEROKU_API_KEY@git.heroku.com/$HEROKU_APP_NAME.git HEAD:main

Understanding the Workflow

What does the above github workflow file means, let''s break it down and understand the steps it's performing to deploy the application on heroku:

Step 1: Trigger

on:
  push:
    tags:
      - 'v*'

This section defines when the workflow will run. It triggers on any push of a tag starting with 'v' (e.g., v1.0.0, v2.1.3). This is useful for deploying specific versions or releases.

Step 2: Job Definition

jobs:
  deploy:
    runs-on: ubuntu-latest

This creates a job named "deploy" that runs on the latest Ubuntu virtual machine provided by GitHub Actions.

Step 3: Checkout Code

steps:
- name: Checkout code
  uses: actions/checkout@v3
  with:
    fetch-depth: 0

This step uses the official GitHub action to clone your repository into the runner.

The fetch-depth: 0 option ensures all tags and history are fetched, which is important for deployments based on tags.

Step 4: Install Heroku CLI

- name: Install Heroku CLI
  run: curl https://cli-assets.heroku.com/install.sh | sh

This step downloads and installs the Heroku Command Line Interface (CLI) on the runner. The CLI is necessary for interacting with Heroku in subsequent steps.

Step 5: Login to Heroku:

- name: Login to Heroku
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
  run: heroku container:login

This step logs into Heroku using the API key stored in GitHub Secrets. The heroku container:login command authenticates with Heroku's container registry, which is necessary for deploying the application.

Note: How to set secrets, we will see after completing the steps of workflow file.

Step 6: Deploy to Heroku:

- name: Deploy to Heroku
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
    HEROKU_APP_NAME: ${{ secrets.HEROKU_APP_NAME }}
  run: |
    git push https://heroku:$HEROKU_API_KEY@git.heroku.com/$HEROKU_APP_NAME.git HEAD:main

This final step performs the actual deployment.

It uses the Heroku API key and app name from GitHub Secrets.

The git push command pushes your code directly to Heroku's Git repository.

HEAD:main ensures that the current commit (HEAD) is pushed to Heroku's main branch, regardless of your local branch name.

By following this workflow, your application will be automatically deployed to Heroku whenever you push a new version tag to your GitHub repository, streamlining your release process.

Setting Up GitHub Secrets

Now let's see how to set the secrets as HEROKU_API_KEY and HEROKU_APP_NAME in GitHub.

1. Log in to your GitHub account with admin privileges.

2. Navigate to the repository's settings.

3. Under the "Security" section, select "Actions" under the "Secrets and variables" section.

4. Click on the "New repository secret" button to create secrets one by one with the names `HEROKU_API_KEY` and `HEROKU_APP_NAME`.

   

- For `HEROKU_API_KEY`, log in to your Heroku account, go to account settings, and reveal or generate a new API key (For the first time use, if it's not already present). Copy and paste this key into GitHub's "Actions secrets and variables".

- For `HEROKU_APP_NAME`, use the name of your application on Heroku.

Here the setup is ready for auto deployment on heroku based on any tag/release we create on github repo.

Testing the Setup

Let's test it.

Either use my previous post mentioned at start of blog to create tag through github website. Or use git bash/command line with commands as:

1. Create a tag:

git tag -a v1.0.0 -m "my version 1.0.0"

'git tag -a' is a command for creating a new annotated tag if it's followed by a tag-name and -m followed by description is used for descripting the tag.

2. Push the tag:

git push origin v1.0.0

This will push the tag to the remote repository.

Pushing the tag will trigger the GitHub Actions workflow for deployment to Heroku. If all steps are followed correctly, the application will be deployed to Heroku.

You can verify the deployment on the Heroku dashboard.

Open heroku dashboard to verify the latest activity. You will notice the new deployment is successful here.

You can also check the "Actions" tab on GitHub to see the status of the workflow. This tab will also help you diagnose any issues if the workflow fails.

As shown in figure on right, there are two failed attempts and two recent successful attempts of github action workflows.

Have a happy auto deployment using github action.

References:

https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

https://git-scm.com/book/en/v2/Git-Basics-Tagging

https://dev.to/heroku/deploying-to-heroku-from-github-actions-29ej