How To Use GitHub Actions for Deployments When Following Trunk-Based Development

Creating a CI/CD pipeline with GitHub Actions and trunk-based development can be challenging without advanced techniques

Dec 14, 2022

10 min read

Nowadays trunk-based development as a branching model is preferred compared to something like Git Flow. But creating a CI/CD pipeline is more challenging since we deploy to every environment from the same branch. In this post, I create a CI/CD pipeline with GitHub actions that deploys to multiple environments. We will start with a basic implementation and improve it step by step.

This post will not be about the basics of GitHub actions and won’t go into details about trunk-based development. We start with a basic introduction to trunk-based development in order to have a shared understanding:

A Brief Introduction to Trunk-Based Development

Trunk-based development involves frequent, small code check-ins to a shared code repository, typically known as the “trunk”. This approach contrasts traditional development models (like Git Flow), which often involve long, isolated development cycles followed by large code merges. In trunk-based development, teams are encouraged to commit their code to the trunk frequently, often multiple times per day. This allows for continuous integration and continuous deployment (CI/CD), as well as easier collaboration and code reviews. You also don’t have branches per environment like a development branch that is deploying to a development environment. You integrate all code on the “trunk”.

Trunk-Based Development is considered the best practice nowadays. You can learn more about it on trunkbaseddevelopment.com.

Creating GitHub Actions Workflows

This is the basic CI/CD pipeline I’d like to create:

At first, we will run some basic checks, then we build the artifact(s) and after that, we deploy it to a staging and a production environment. Yes, we can do a lot more like integration and E2E tests, more environment etc. but this should be sufficient to showcase the main points.

I will be using an AWS CDK deployment as an example but the pipelines will be applicable for everything that creates some kind of a deployable artifact (like a dist folder).

The Basic GitHub Action Workflow

Let us start with a very basic pipeline. We will build upon that and refine it in the following sections.

This is how the code for a basic GitHub Action that deploys to a staging and a production environment could look like:

1
on:
2
  push:
3
    branches:
4
      - main # your "trunk" branch
5
jobs:
6
  build-and-delopy:
7
    name: Build & Deploy
8
    runs-on: ubuntu-latest
9
    # Required for GH OIDC
10
    permissions:
11
      id-token: write
12
      contents: read
13
    steps:
14
      - name: Checkout
15
        uses: actions/checkout@v3
16
      - name: Setup Node and Cache
17
        uses: actions/setup-node@v3
18
        with:
19
          node-version: 16.18
20
          cache: npm
21
      - name: Install dependencies
22
        run: npm ci
23
      - name: Type Check
24
        run: npm run type-check
25
      - name: Unit Tests
26
        run: npm run test
27
      - name: Create Artifact
28
        run: npm run synth # often 'npm run build'
29
      - name: Configure AWS credentials
30
        uses: aws-actions/configure-aws-credentials@v1-node16
31
        with:
32
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
33
          aws-region: eu-central-1
34
      - name: Deploy Artifact to Staging
35
        run:
36
          npx cdk deploy --app "./cdk.out/assembly-Staging" --all --concurrency 10 --method=direct --require-approval
37
          never
38
      - name: Deploy Artifact to Production
39
        run:
40
          npx cdk deploy --app "./cdk.out/assembly-Prod" --all --concurrency 10 --method=direct --require-approval never

We trigger the pipeline on pushes to main (our “trunk”). Remember, we don’t have different branches per environment. We deploy to all our environments from this branch.

We have one single job build-and-delopy that includes all our steps of the pipeline. The steps are implementing the flow that is shown in the introduction of this chapter. We build the artifacts that should be deployed once and then deploy them to the different environments. We store our secrets in the GitHub secrets of the repository (AWS_DEPLOY_ROLE_ARN in this case).

Sidenote: I am using Open ID Connect to get short-lived credentials for my AWS account. This is a security best practice and safer than using long-lived credentials like a username and password via environment variables.

While this already works, we can do better by leveraging GitHub environments.

Leveraging GitHub Environments

GitHub environments provide some additional features like specifying different secrets per environment (with the same name), having a deployment history per environment, and more. You can learn more about environments and their features in the GitHub documentation.

Environments have to be configured per job in our GitHub Action workflow. Currently, we only have a single job. Now we split it up into three distinct jobs: build, deploy-staging and deploy-production. This is what it looks like:

1
on:
2
  push:
3
    branches:
4
      - main # your "trunk" branch
5
jobs:
6
  build:
7
    name: Build
8
    runs-on: ubuntu-latest
9
    steps:
10
      - name: Checkout repo
11
        uses: actions/checkout@v3
12
      - name: Setup Node and Cache
13
        uses: actions/setup-node@v3
14
        with:
15
          node-version: 16.18
16
          cache: npm
17
      - name: Install dependencies
18
        run: npm ci
19
      - name: Type Check
20
        run: npm run type-check
21
      - name: Unit Tests
22
        run: npm run test
23
      - name: Create Artifact
24
        run: npm run synth # often 'npm run build'
25
      - name: Upload Artifact
26
        uses: actions/upload-artifact@v3
27
        with:
28
          name: cdk-out
29
          path: cdk.out # often 'dist'
30
  deploy-staging:
31
    name: Deploy to Staging
32
    runs-on: ubuntu-latest
33
    needs: build
34
    environment: staging
35
    # required to interact with GitHub's OIDC Token endpoint
36
    permissions:
37
      id-token: write
38
      contents: read
39
    steps:
40
      - name: Download Artifact
41
        uses: actions/download-artifact@v3
42
        with:
43
          name: cdk-out
44
          path: cdk.out
45
      - name: Configure AWS credentials
46
        uses: aws-actions/configure-aws-credentials@v1-node16
47
        with:
48
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
49
          aws-region: eu-central-1
50
      - name: Deploy Artifact
51
        run:
52
          npx cdk deploy --app "./cdk.out/assembly-Staging" --all --concurrency 10 --method=direct --require-approval
53
          never
54
  deploy-production:
55
    name: Deploy to Production
56
    runs-on: ubuntu-latest
57
    needs: [build, staging] # build - if you want to deploy in parallel with Staging
58
    environment: production
59
    # required to interact with GitHub's OIDC Token endpoint
60
    permissions:
61
      id-token: write
62
      contents: read
63
    steps:
64
      - name: Download Artifact
65
        uses: actions/download-artifact@v3
66
        with:
67
          name: cdk-out
68
          path: cdk.out
69
      - name: Configure AWS credentials
70
        uses: aws-actions/configure-aws-credentials@v1-node16
71
        with:
72
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
73
          aws-region: eu-central-1
74
      - name: Deploy Artifact
75
        run:
76
          npx cdk deploy --app "./cdk.out/assembly-Prod" --all --concurrency 10 --method=direct --require-approval never

The new parts are the uploading and downloading of the artifact that is created in the build job and the environment per environment-specific job.

By uploading and downloading the initially created artifacts we only have to actually build the artifacts once and can be sure that they are stable (and not differ due to different builds).

After running this pipeline for the first to you’ll the the “Environments” sections in the sidebar in your GitHub repository:

A red arrow indicating the position where the environments are shown on the GitHub UI.

When clicking on it you will see the deployment history of that environment:

The deployment history for the production environment in the GitHub UI.

Ideally, your history looks a lot greener 😅

In addition to that, we can now re-run only the failed jobs (and not our whole pipeline). That was not possible with one job.

Okay, this is an improvement, but there is one more thing: Often you don’t want to automatically deploy to production but rather have a manual trigger in order to promote the artifact to production in order to have the opportunity to check the staging environment before actually releasing your changes to the user. How to do that with GitHub Actions?

Adding a Manual Trigger for a Production Deployment

You can activate the “Required reviewers” config for your production environment under Settings -> Environments -> production:

That way you don’t have to change anything in your pipeline. This is what it looks like:

It will not be deployed to production without a review by an authorized person.

Unfortunately, this simple solution is often not an option. For private repositories, it is only available to GitHub Enterprise customers and it has some other limitations like max. 6 authorized reviewers (teams are also possible). You can learn more about reviewing deployments in the GitHub documentation.

There is an alternative to that using releases.

Using Releases for Manual Steps

Instead of one workflow with all of our jobs, we will now have two. One for building the artifacts, deploying to staging, and creating a release, and a second one for deploying to production if a specific release has been published.

This is how the first workflow now looks like:

1
on:
2
  push:
3
    branches:
4
      - main # your "trunk" branch
5
jobs:
6
  #
7
  # the 'build' and 'deploy-staging' jobs stay exactly the same; omitted
8
  #
9
  create-release:
10
    name: Create Release
11
    runs-on: ubuntu-latest
12
    needs: build
13
    steps:
14
      - name: Download Artifact
15
        uses: actions/download-artifact@v3
16
        with:
17
          name: cdk-out
18
          path: cdk.out
19
      # we can't attack a folder to a release
20
      - name: Zip Artifact
21
        run: |
22
          zip -r cdk.out.zip cdk.out
23
      - name: Create Release Tag
24
        id: create-release-tag
25
        # left pads the run number with zeros to a length of 4; better alphabetical order
26
        run: echo "tag_name=r-$(printf %04d $GITHUB_RUN_NUMBER)" >> $GITHUB_OUTPUT
27
      - name: Create Draft Release
28
        uses: softprops/action-gh-release@v1
29
        with:
30
          tag_name: ${{ steps.create-release-tag.outputs.tag_name }}
31
          name: Release ${{ steps.create-release-tag.outputs.tag_name }}
32
          body: |
33
            ## Info
34
            Commit ${{ github.sha }} was deployed to `staging`. [See code diff](${{ github.event.compare }}).
35

36
            It was initialized by [${{ github.event.sender.login }}](${{ github.event.sender.html_url }}).
37

38
            ## How to Promote?
39
            In order to promote this to prod, edit the draft and press **"Publish release"**.
40
          draft: true
41
          files: cdk.out.zip

We download the artifact from the build job, zip it, and create a release as a draft attaching the zipped artifact. The body of the release can be written in markdown. You can add additional information to the release itself. Here you find a reference to the information that is available in a push-triggered workflow.

Releases are always tied to tags. I have created a basic tag name that uses the GITHUB_RUN_NUMBER with a prefix. I also added some left padding to have the releases show up in alphabetical order. If you use semver or any other convention you can change the tag name there.

This is an example release that has been created with the previously shown workflow:

Editing that draft release and clicking on “Publish release” will trigger the next workflow that deploys the artifacts to production:

1
on:
2
  release:
3
    types: [published]
4

5
jobs:
6
  release-production:
7
    name: Release to Production
8
    if: startsWith(github.ref_name, 'r-') # the prefix we have added to the tag
9
    environment: production
10
    runs-on: ubuntu-latest
11
    permissions:
12
      id-token: write
13
      contents: read
14
    steps:
15
      - name: Get Artifact from Release
16
        uses: dsaltares/fetch-gh-release-asset@master
17
        with:
18
          version: ${{ github.event.release.id }}
19
          file: cdk.out.zip
20
      - name: Unzip Artifact
21
        run: unzip cdk.out.zip
22
      - name: Configure AWS credentials
23
        uses: aws-actions/configure-aws-credentials@v1-node16
24
        with:
25
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
26
          aws-region: eu-central-1
27
      - name: Deploy Artifact
28
        run:
29
          npx cdk deploy --app "./cdk.out/assembly-Prod" --all --concurrency 10 --method=direct --require-approval never

This workflow gets triggered on the release published event which gets triggered after a release, pre-release, or draft of a release was published. You can look up the details on the release published event in the GitHub documentation. In addition to that, we only run the release-production job if the reference of the release that triggered the workflow starts with the prefix for the tag we have created earlier.

That is it. You can see the published releases in the sidebar on the GitHub UI:

I like this approach since you have GitHub releases for your actual production releases. That releases have the deployed artifacts attached. That way you can re-deploy any previously deployed artifact easily. This enables rollbacks to previous releases.

Conclusion

GitHub Actions provide us with a lot of opportunities. I myself haven’t used features like up-/downloading artifacts, environments, creating releases etc. Knowing about them opens up new doors. I now prefer having multiple jobs that I can re-run independently instead of a single job that is doing everything. (I was actually wondering for a long time what the difference between “Re-run all jobs” vs. “Re-run failed jobs” is. There were none for me.)

Hopefully, you learned a thing and maybe can use it in your own GitHub Action workflows.