Automate your releases with CircleCI and the GitHub CLI orb

Last year, GitHub announced the release of their new CLI tool. The new gh CLI wraps around the standard git cli and offers a suite of additional GitHub.com specific commands. These new commands include the ability to create a new pull request and to create a release directly from your terminal.

We here on the CircleCI Community and Partner Engineering team at CircleCI use the gh pr checkout command all the time to safely test pull requests from the community (you!) on our various orbs.

Today we are sharing the new GitHub CLI orb. You can now bring the power and flexibility of the GitHub CLI to your CI/CD pipeline.

What are orbs?

Orbs are reusable packages of CI configuration that can be used in your CircleCI config to automate and optimize CI tasks. With orbs you can test and deploy a Node.js application or easily add customizable Slack notifications to your CI pipeline.

Now that the GitHub CLI orb is available, we can show you how we combine the power of CircleCI and GitHub to automate our test and release process.

Testing the code

The ultimate goal of our config is to have a CI/CD pipeline where code on any branch will always be tested. In this case, if we merge our changes to the main branch, we want to then tag and release that update on GitHub.com.

To begin, we will start with a sample config of a very simple Node.js project, on which we will run npm run test on every commit pushed to the repository, on all branches.

version: '2.1'
orbs:
  node: circleci/node@4.3
workflows:
  test-and-release:
    jobs:
      - node/test

This config file contains a workflow test-and-release containing a single node/test job provided by the Node orb. This job automatically checks out our code, installs and caches our dependencies, and runs our test npm script. If you want to see an example of what this job looks like in action, you can view this live example in the CircleCI app.

Now, our tests are run for us automatically but when it comes time to issue a new release of our product, we will need to manually create a tag and release on GitHub.com. We can take advantage of the new GitHub CLI orb and our CircleCI config to automate this process.

Preparing GitHub authentication

For automatically creating tags and releases, we will use the GitHub CLI and token based authentication. First, we will create a GitHub token with the proper permissions, and then we will add the token to a CircleCI context.

A context on CircleCI is a shared collection of environment variables that can be attached to various jobs in any project within an organization. This is useful when you need to share credentials (like GitHub authentication) between many projects. Contexts can even be restricted to prevent jobs from accessing a context unless triggered by a user with the proper permissions.

Begin by creating a GitHub personal access token.

The permission scopes needed for the GitHub CLI are repo and read:org.

Once you have your personal access token handy, head over to https://app.circleci.com/ and in the left vertical navigation bar, select the gear icon for Organization Settings. This opens the contexts settings page. The URL will look something like this: https://app.circleci.com/settings/organization/<VCS>/<Organization>/contexts

Click Create Context and give it a name. In our example we will use GITHUB_CREDS.

Then, click Add Environment Variable and add your token, using the name GITHUB_TOKEN.

Automating the release

Begin by adding the GitHub CLI orb to your config:

version: '2.1'
orbs:
  node: circleci/node@4.3
  gh: circleci/github-cli@1.0

This gives us access to the various commands and jobs offered by the GitHub CLI orb. Commands can be used in your custom jobs to set up and authenticate with the CLI for manual use, but in this example we will use the release job with some customized parameters and filters.

Implementing a complete test and release workflow with the GitHub CLI orb

version: '2.1'
orbs:
  node: circleci/node@4.3
  gh: circleci/github-cli@1.0
workflows:
  test-and-release:
    jobs:
      - node/test
      - gh/release:
          notes-file: changelog.md
          tag: 1.0.0
          title: The initial release
          requires:
            - node/test
          context:
            - GITHUB_CREDS
          filters:
            branches:
              only:
                - main

You can see we have added the gh/release job to our test-and-release workflow with a number of customized parameters. You can view all available parameters for the job on the Orb Registry page for this orb job. This job automatically runs the gh/setup command, which installs and authenticates the GitHub CLI, and then runs gh release create with our specified parameters.

Imagine you are working on the first major release of your product. For now, you are working in the beta branch. When the beta is complete, you plan to merge to main and issue version 1.0.0 of your release.

Looking at the full example, we are providing the (required) tag parameter to specify the intended release tag. If no such tag exists, the gh cli will create a new tag using the latest code in the default branch, which in our case is main.

There are three additional parameters shown here that are not from the orb directly, so you will not see them on the Orb Registry docs. Parameters requires, context, and filters are special job parameters available to any job on CircleCI natively.

• The requires parameter specifies that this job (gh/release) will not run until all jobs under requires have completed successfully. In this case the job is node/test.
• The context contains our shared environment variables. Here is where we can attach the GITHUB_CREDS context we created earlier.
• Filters limit the conditions under which a job will execute. Without any filters, all jobs in a workflow will always execute. With the filter applied in this example, our gh/release job will run only if the job was triggered on the main branch (when we merge).

This means that when we merge our change from beta to main in the config setup, the 1.0.0 tag and release will be created from the new HEAD of main that contains our new changes.

In the example above, we used several additional parameters to specify the location of the changelog file, set the title, and more.

Wrapping up

After implementing the test and release workflow, we can just update our .circleci/config.yml with each pull request to reflect the desired change. For example, if we were to open a new branch called add-feature-blink, we would start our new branch by updating the config to reflect the intended release we want to prepare for when we are again ready to merge to main:

workflows:
  test-and-release:
    jobs:
      - node/test
      - gh/release:
          notes-file: changelog.md
          tag: 1.1.0
          title: "Add Feature: Blinking text"

Thank you for reading!

Kyle Tryon @TechSquidTV

View the GitHub CLI orb.