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: email@example.com 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
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:
Click Create Context and give it a name. In our example we will use
Then, click Add Environment Variable and add your token, using the name
Automating the release
Begin by adding the GitHub CLI orb to your config:
version: '2.1' orbs: node: firstname.lastname@example.org gh: email@example.com
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: firstname.lastname@example.org gh: email@example.com 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
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
filters are special job parameters available to any job on CircleCI natively.
requiresparameter specifies that this job (
gh/release) will not run until all jobs under
requireshave completed successfully. In this case the job is
- The context contains our shared environment variables. Here is where we can attach the
GITHUB_CREDScontext 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/releasejob will run only if the job was triggered on the
mainbranch (when we merge).
This means that when we merge our change from
main in the config setup, the
1.0.0 tag and release will be created from the new
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.
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
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.