Using GitHub CLI in Workflows

1. Using gh auth

Option	Values	Description
gh auth login	`gh auth login`	Authenticates the GitHub CLI with your GitHub account
gh auth token	`gh auth token`	Outputs the personal access token for authentication
gh auth status	`gh auth status`	Displays the current authentication status

gh auth login

Example: Retrieving the authentication token

gh auth token

Note: The gh auth login command will prompt you to select an authentication method (e.g., browser-based or token-based). For CI/CD environments like GitHub Actions, it's recommended to use a personal access token.

2. Using gh pr Commands

Command	Description	Example
gh pr create	Create a new pull request	`gh pr create --title "feat: add new feature" --body "This PR adds a new feature to the project."`
gh pr checkout <pr-number>	Checkout a pull request locally	`gh pr checkout 123`
gh pr status	Check the status of pull requests	`gh pr status`
gh pr list	List open pull requests	`gh pr list --state open`
gh pr comment <pr-number>	Add a comment to a pull request	`gh pr comment 123 --body "Please review this change."`
gh pr merge <pr-number>	Merge a pull request	`gh pr merge 123 --merge`

Note: Ensure that the gh CLI is installed and authenticated in your GitHub Actions workflow using gh auth login.

3. Using gh issue Commands

Command	Description	Example
gh issue create	Create a new issue	`gh issue create --title "Bug in login flow" --body "User cannot login after entering wrong credentials" --assignee "john-doe"`
gh issue list	List issues in a repository	`gh issue list --label "bug" --state open`
gh issue view	View details of a specific issue	`gh issue view 123 --web`
gh issue comment	Add a comment to an issue	`gh issue comment 123 --body "This issue has been resolved in PR #456"`
gh issue close	Close an issue	`gh issue close 123 --reason "not planned"`

Note: The gh CLI must be installed in the workflow environment to use these commands.

4. Using gh release Commands

Command	Description	Notes
gh release create	Creates a new release	Requires `GITHUB_TOKEN` with `contents: write` permission
gh release list	Lists existing releases	Supports filtering by tag or pre-release status
gh release delete	Deletes a release by tag	Cannot be undone; use with caution
gh release upload	Uploads assets to a release	Supports multiple files and directories

Example: Create a Release

gh release create v1.0.0 \
  --title "Release v1.0.0" \
  --notes "Release notes for version 1.0.0" \
  --draft

Example: Upload Assets to Release

gh release upload v1.0.0 \
  dist/app.zip \
  dist/app.tar.gz

Note: The gh release commands require the GitHub CLI (gh) to be installed in the runner environment.

Warning: Ensure that GITHUB_TOKEN has appropriate permissions (e.g., contents: write) to create and modify releases.

5. Using gh repo Commands

Command	Description	Notes
gh repo clone <repo>	Clone a repository locally	Useful for checking out code in workflows
gh repo create <repo>	Create a new repository	Can be used to initialize a new repo from workflow
gh repo view <repo>	View repository information	Displays metadata like description, topics, etc.
gh repo list <owner>	List repositories for an owner	Useful for automation or fetching repo lists

Example: Clone a repository

gh repo clone owner/repo-name

Example: Create a new repository

gh repo create my-new-repo --public

Note: The gh CLI must be installed in the runner environment to use these commands.

6. Using gh run Commands

Command	Description	Notes
gh run list	List workflow runs	Lists recent runs with status, branch, and commit
gh run view	View details of a specific run	Shows logs, jobs, and steps for a run
gh run watch	Watch a run until completion	Streams logs in real-time
gh run cancel	Cancel a running workflow run	Can only cancel runs in progress
gh run download	Download artifacts from a run	Downloads all or specific artifacts

Example: List recent workflow runs

gh run list --branch main --limit 5

Example: View a specific run

gh run view 123456789 --job 1234567890

Example: Cancel a running run

gh run cancel 123456789

Note: The gh run commands require the GitHub CLI to be installed and authenticated in the workflow environment.

7. Using gh workflow Commands

Command	Description	Example
gh workflow run	Trigger a workflow run manually	`gh workflow run "Build and Test"`
gh workflow list	List all workflows in the repository	`gh workflow list`
gh workflow view	View the YAML content of a workflow	`gh workflow view "deploy.yml"`
gh workflow disable	Disable a workflow	`gh workflow disable "build.yml"`
gh workflow enable	Enable a disabled workflow	`gh workflow enable "build.yml"`

Note: The gh workflow commands require the GitHub CLI to be installed and authenticated in the environment where the command is run.

8. Using gh api Commands

Command	Description	Example
gh api	Make requests to the GitHub API	`gh api repos/octocat/Hello-World/issues`
gh api --method	Specify HTTP method (GET, POST, PUT, DELETE)	`gh api --method POST repos/octocat/Hello-World/issues`
gh api --header	Add custom headers to the request	`gh api --header "Accept: application/vnd.github.v3+json" repos/octocat/Hello-World`
gh api --jq	Filter JSON response using jq syntax	`gh api repos/octocat/Hello-World/issues --jq ".[] \| .title"`

Example: Fetching Issues from a Repository

gh api repos/octocat/Hello-World/issues

Example: Creating a New Issue

gh api --method POST repos/octocat/Hello-World/issues \
  --header "Accept: application/vnd.github.v3+json" \
  --json "{ \"title\": \"New Issue via CLI\", \"body\": \"This issue was created using gh api.\" }"

9. Formatting gh Output

Format	Description	Example
json	Outputs structured JSON data	`gh issue list --json title,number`
json	Outputs structured JSON data with custom fields	`gh issue list --json title,number,author`
table	Formats output as a table (default)	`gh issue list --state open`
plain	Outputs plain text without formatting	`gh issue list --state open --format plain`
yaml	Outputs structured YAML data	`gh issue list --state open --format yaml`

Example: Using JSON format to parse output

gh issue list --json title,number --state open | jq '.[] | "Issue \(.number): \(.title)"'

Note: The --json format is useful for scripting and parsing in tools like jq.

Example: Using table format for readable output

gh issue list --state open --format table

Warning: When using --json, the output is not human-readable and should be processed with tools like jq or python.

10. Using gh Extensions

Extension	Description	Installation	Usage
gh extension install	Installs a GitHub CLI extension	`gh extension install owner/repo`	`gh extension install owner/repo`
gh extension list	Lists installed extensions	`gh extension list`	`gh extension list`
gh extension upgrade	Upgrades an installed extension	`gh extension upgrade owner/repo`	`gh extension upgrade owner/repo`

Example: Installing and Using a GitHub CLI Extension

gh extension install owner/repo
gh extension list
gh repo view owner/repo

Note: Extensions must be installed in the workflow using gh extension install before they can be used.

11. Automating with gh Scripts

Script	Description	Usage
gh script run	Executes a GitHub CLI script	`gh script run <script-name>`
gh script list	Lists all available scripts	`gh script list`
gh script create	Creates a new script	`gh script create <script-name>`

Example: Running a Script

gh script run deploy-script

Example: Creating a Script

gh script create deploy-script

Note: Scripts must be stored in the .github/scripts directory.

12. Authenticating gh

Method	Description	Requirements	Notes
Personal Access Token (PAT)	Use a PAT with appropriate scopes for the operations you need to perform.	A valid GitHub PAT with required scopes (e.g., `repo`, `workflow`)	Recommended for most use cases. Store as a secret in your repository.
GitHub App Token	Generate a token from a GitHub App for more granular permissions.	GitHub App installed on the repository or organization	Useful for fine-grained access control and better security in shared environments.
OAuth Token	Use an OAuth token for specific scopes and permissions.	OAuth app registered with GitHub	Less common in workflows; primarily used for user-level operations.

Example: Using a Personal Access Token

name: Use GitHub CLI
on:
  push:
    branches: [ main ]
jobs:
  use-gh:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup gh CLI
        uses: actions/setup-cli@v1
        with:
          cli: gh
      - name: Authenticate with token
        run: |
          echo ${{ secrets.GITHUB_TOKEN }} | gh auth login --with-token

Note: The GITHUB_TOKEN is automatically available in workflows and can be used to authenticate with the gh CLI.

Warning: Avoid hardcoding tokens in workflow files. Always use secrets.