Using GitHub CLI to Remotely Perform Actions

Contents

1. Introduction
2. Prerequisites
3. Authentication Setup
4. Performing Actions with GitHub CLI
   • Publishing a Release
   • Running a Workflow
5. Conclusion

Introduction

The GitHub CLI allows you to interact with your GitHub repositories directly from the command line. This can be especially useful for performing actions like publishing releases and triggering workflows without having to navigate the web interface. In this post, we’ll walk through how to set up the GitHub CLI and use it to perform some common actions.

Prerequisites

Before you begin, you’ll need to ensure the following:

1. SSH key setup: Make sure you have your SSH key configured locally for authentication.
2. GitHub Personal Access Token: You'll need a personal access token with the necessary permissions. Specifically, you'll need the following scopes:
   • repo
   • read:org
   • admin:public_key
3. GitHub CLI installed: If you don’t already have the GitHub CLI installed, you can install it using the following command:

brew install gh

Authentication Setup

Once you have the prerequisites ready, you can authenticate GitHub CLI with your GitHub account using the following steps.

Run the following command to initiate the login process:

gh auth login

This will take you through a series of prompts, for example:

~/dev/johno
❯ gh auth login
? Where do you use GitHub? GitHub.com
? What is your preferred protocol for Git operations on this host? SSH
? Upload your SSH public key to your GitHub account? Skip
? How would you like to authenticate GitHub CLI? Paste an authentication token
Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo', 'read:org'.
? Paste your authentication token: ****************************************
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as jonsully1

Performing Actions with GitHub CLI

Once you’re authenticated, you can use GitHub CLI to carry out various actions. Here are a couple of examples.

Publishing a Release

To create a new release and generate release notes, use the following command:

gh release create 0.1.0-rc1 --target develop --generate-notes

This will create a release for version 0.1.0-rc1, targeting the develop branch and automatically generating release notes.

Running a Workflow

You can also trigger GitHub Actions workflows directly from the command line. For example, to trigger a Terraform plan workflow, you can use the following command:

gh workflow run "Terraform Plan" -f environment=qa --ref main

for example:

~/dev/johno
❯ gh workflow run "Terraform Plan" -f environment=qa --ref main
✓ Created workflow_dispatch event for terraform-plan.yml at main

To see runs for this workflow, try: gh run list --workflow=terraform-plan.yml

This will create a workflow_dispatch event for the terraform-plan.yml workflow, targeting the main branch with the qa environment.

As you can see from the response above, you can also check the status of your workflow runs from the CLI:

~/dev/johno
❯ gh run list --workflow=terraform-apply.yml
STATUS  NAME                                  WORKFLOW         BRANCH  EVENT              ID           ELAPSED  AGE
*       Route53 (dev): Add new hosted zone    Terraform Apply  main    workflow_dispatch  14338645008  7s       0m

Conclusion

If you’re frequently working with GitHub Actions or managing releases, using gh is a great way to streamline your workflow.

Thanks for reading.

John O