> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/github-cli

Manage your GitHub projects in your CI pipeline with the GitHub CLI orb integration.


## Commands

### clone

A GitHub specific alternative to CircleCI's native "checkout" command.
Use the GitHub CLI to clone the current repository, or specify an alternative repo via parameters.
https://cli.github.com/manual/gh_repo_clone.
This requires read:org permissions on a private repo.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | string |  | Branch to checkout. Value defaults to empty, which will clone the default branch. |
| `dir` | string | . | Select the path to clone into. By default the current path will be selected, which is dictated by the job's "working_directory". |
| `hostname` | string | github.com | Specify the hostname of the GitHub instance to authenticate with. |
| `repo` | string | $CIRCLE_REPOSITORY_URL | Enter either the name of the repository or the full repository URL. Will default to the current project. |
| `when` | string | on_success | Specify when to run this command. Options are "on_success", "always" or "on_fail". |

### install

Install the gh cli without authenticating or configuring. This command should be run before invoking the gh cli.
This requires read:org permissions on private repos.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `max_retries` | integer | 5 | Max of retries to do when the request to github releases fails. |
| `version` | string | latest | Specify the full semver versioned tag to use. Default to latest. |
| `when` | string | on_success | Specify when to run this command. Options are "on_success", "always" or "on_fail". |

### setup

Install and authenticate with the gh cli. This command should be run before invoking the gh cli.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `hostname` | string | github.com | Specify the hostname of the GitHub instance to authenticate with. |
| `max_retries` | integer | 5 | Max of retries to do when the request to github releases fails. |
| `token` | env_var_name | GITHUB_TOKEN | Enter the name of the environment variable containing the GitHub Personal Access token to be used for authentication.
It is recommended for CI processes that you create a "machine" user on GitHub.com with the needed permissions, rather than using your own.
 |
| `version` | string | latest | Specify the full semver versioned tag to use. Default to latest. |
| `when` | string | on_success | Specify when to run this command. Options are "on_success", "always" or "on_fail". |

## Jobs

### pr-merge

Merge pull request to target branch. See more at https://cli.github.com/manual/gh_pr_merge. This requires write:discussion permissions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Enter any additional arguments to pass to the `gh pr merge` command (e.g. --squash) |
| `branch` | string | $CIRCLE_BRANCH | Enter PR number, branch or URL to merge. Without an argument, the pull request that belongs to the current branch is selected |
| `hostname` | string | github.com | Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance.
 |
| `repo` | string | $CIRCLE_REPOSITORY_URL | Enter either the name of the repository or the full repository URL. Will default to the current project. |
| `token` | env_var_name | GITHUB_TOKEN | Enter the name of the environment variable containing the GitHub Personal Access token to be used for authentication. It is recommended for CI processes that you create a "machine" user on GitHub.com with the needed permissions, rather than using your own.
 |
| `version` | string | 2.20.2 | Specify the full semver versioned tag to use for the GitHub CLI installation. |

### release

Create a new GitHub Release for a repository. Specify a tag with the `tag` parameter (required). If a matching git tag does not yet exist, one will automatically get created from the latest state of the default branch. This requires write:packages permissions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Specify additional arguments to pass to the GitHub CLI command.
See the GitHub CLI documentation for a list of available arguments: https://cli.github.com/manual/gh_release_create
 |
| `clone` | boolean | true | Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo. |
| `dir` | string | . | Select the path to clone into. By default the current path will be selected, which is dictated by the job's "working_directory".
The release will be done from this path.
 |
| `draft` | boolean | false | Save the release as a draft instead of publishing it. |
| `files` | string |  | To include a subset of your repository's files in the release, enter the file glob here. (e.g. ./dist/*.tgz)  |
| `hostname` | string | github.com | Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance. |
| `notes-file` | string |  | Path to file containing release notes (e.g.: ./changelog.md).  |
| `prerelease` | boolean | false | Mark the release as a prerelease. |
| `tag` | string |  | Select a tag to create a release from. If a matching git tag does not yet exist, one will automatically get created from the latest state of the default branch. |
| `title` | string |  | Include a release title.  |
| `token` | env_var_name | GITHUB_TOKEN | Enter the name of the environment variable containing the GitHub Personal Access token to be used for authentication.
It is recommended for CI processes that you create a "machine" user on GitHub.com with the needed permissions, rather than using your own.
 |
| `version` | string | latest | Specify the full semver versioned tag to use for the GitHub CLI installation. Default to latest. |

### upload

Upload assets to an existing GitHub Release. Specify a tag matching the release with the `tag` parameter (required). See more at https://cli.github.com/manual/gh_release_upload. This requires write:packages permissions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional_args` | string |  | Enter any additional arguments to pass to the `gh release upload` command (e.g. --clobber) |
| `clone` | boolean | true | Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo. |
| `dir` | string | . | Select the path to clone into. By default the current path will be selected, which is dictated by the job's "working_directory".
The upload will be done from this path.
 |
| `files` | string |  | To include a subset of your repository's files in the release, enter the file glob here. (e.g. ./dist/*.tgz)  |
| `hostname` | string | github.com | Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance.
 |
| `tag` | string | $CIRCLE_TAG | Specify the tag which the asset files will be uploaded to. A GitHub Release matching the tag must already exist.
 |
| `token` | env_var_name | GITHUB_TOKEN | Enter the name of the environment variable containing the GitHub Personal Access token to be used for authentication. It is recommended for CI processes that you create a "machine" user on GitHub.com with the needed permissions, rather than using your own.
 |
| `version` | string | 2.20.2 | Specify the full semver versioned tag to use for the GitHub CLI installation. |

## Examples

### create_release

Use the GitHub CLI to issue a new release as a part of your CircleCI pipeline. In this example, on every commit (merge) to the "main" branch, we will use the config to specify the desired tag and issue a release. Add a Context containing your GITHUB_TOKEN and GITHUB_HOSTNAME (optional) or set a project-level environment variable.


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

### install

Simply install the GitHub CLI for manual usage. The `install` command is used to install the GitHub CLI without authenticating or configuring it. Once the installation is complete, you can utilize the CLI manually, or use any of the other provided orb commands, such as `clone`.


```yaml
version: '2.1'
orbs:
  gh: circleci/github-cli@2.8
jobs:
  create-a-deployment:
    docker:
      - image: cimg/base:stable
    steps:
      - gh/install
      - run:
          command: >
            gh api /repos/:owner/:repo/deployments --preview ant-man --input - \

            --jq '"export GH_DEPLOYMENT_STATUS_URL=\(.statuses_url)"' >>
            $BASH_ENV \<<JSON || true

            {

            "ref": "${CIRCLE_TAG:-$CIRCLE_SHA1}",

            "environment": "${AWS_ENVIRONMENT,,}",

            "auto_merge": false,

            "required_contexts": []

            }

            JSON
          name: Create Deployment
workflows:
  use-my-orb:
    jobs:
      - create-a-deployment
```

### pr-merge

Use the GitHub CLI merge pull request automatically. Usually it can be a pull request from a bot like Dependabot. In this example, on every Dependabot pull request, we run tests and merge the PR if tests pass Add a Context containing your GITHUB_TOKEN and GITHUB_HOSTNAME (optional) or set a project-level environment variable.


```yaml
version: '2.1'
orbs:
  gh: circleci/github-cli@2.8
workflows:
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build
      - gh/pr-merge:
          additional-args: '--rebase  --delete-branch'
          context:
            - GITHUB_CREDS
          filters:
            branches:
              only: /^dependabot.*/
          requires:
            - test
```

### setup

Simply install the GitHub CLI for manual usage. The `setup` command is used to install and authenticate the GitHub CLI. Once the setup is complete, you can utilize the CLI manually, or use any of the other provided orb commands, such as `clone`.


```yaml
version: '2.1'
orbs:
  gh: circleci/github-cli@2.8
jobs:
  create-a-pr:
    docker:
      - image: cimg/base:stable
    steps:
      - gh/setup
      - run:
          command: |
            gh pr create --title "Bugfix from $CIRCLE_BRANCH"
          name: Create Pull Request
      - gh/clone
workflows:
  use-my-orb:
    jobs:
      - create-a-pr
```