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 underrequires
have completed successfully. In this case the job isnode/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 themain
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.