1. circleci/github-cli@dev:alpha

circleci/github-cli@dev:alpha

Certified
Sections
Manage your GitHub projects in your CI pipeline with the GitHub CLI orb integration.
Created: May 4, 2021Version Published: December 17, 2024Releases: 18
Org Usage:
649
Categories:

Orb Quick Start Guide

Use CircleCI version 2.1 at the top of your .circleci/config.yml file.

1 version: 2.1

Add the orbs stanza below your version, invoking the orb:

1 2 orbs: github-cli: circleci/github-cli@dev:alpha

Use github-cli elements in your existing workflows and jobs.

Usage 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 version: '2.1' orbs: gh: circleci/github-cli@2.6 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`.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 version: '2.1' orbs: gh: circleci/github-cli@2.6 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 version: '2.1' orbs: gh: circleci/github-cli@2.6.0 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`.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 version: '2.1' orbs: gh: circleci/github-cli@2.6 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

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.

Show job Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
additional_args
Enter any additional arguments to pass to the `gh pr merge` command (e.g. --squash)
No
''
string
branch
Enter PR number, branch or URL to merge. Without an argument, the pull request that belongs to the current branch is selected
No
$CIRCLE_BRANCH
string
hostname
Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance.
No
github.com
string
repo
Enter either the name of the repository or the full repository URL. Will default to the current project.
No
$CIRCLE_REPOSITORY_URL
string
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.
No
GITHUB_TOKEN
env_var_name
version
Specify the full semver versioned tag to use for the GitHub CLI installation.
No
2.20.2
string

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.

Show job Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
additional_args
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
No
''
string
clone
Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo.
No
true
boolean
dir
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.
No
.
string
draft
Save the release as a draft instead of publishing it.
No
false
boolean
files
To include a subset of your repository's files in the release, enter the file glob here. (e.g. ./dist/*.tgz)
No
''
string
hostname
Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance.
No
github.com
string
notes-file
Path to file containing release notes (e.g.: ./changelog.md).
No
''
string
prerelease
Mark the release as a prerelease.
No
false
boolean
tag
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.
Yes
-
string
title
Include a release title.
No
''
string
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.
No
GITHUB_TOKEN
env_var_name
version
Specify the full semver versioned tag to use for the GitHub CLI installation. Default to latest.
No
latest
string

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.

Show job Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
additional_args
Enter any additional arguments to pass to the `gh release upload` command (e.g. --clobber)
No
''
string
clone
Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo.
No
true
boolean
dir
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.
No
.
string
files
To include a subset of your repository's files in the release, enter the file glob here. (e.g. ./dist/*.tgz)
Yes
-
string
hostname
Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance.
No
github.com
string
tag
Specify the tag which the asset files will be uploaded to. A GitHub Release matching the tag must already exist.
No
$CIRCLE_TAG
string
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.
No
GITHUB_TOKEN
env_var_name
version
Specify the full semver versioned tag to use for the GitHub CLI installation.
No
2.20.2
string

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.

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

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.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
version
Specify the full semver versioned tag to use. Default to latest.
No
latest
string
when
Specify when to run this command. Options are "on_success", "always" or "on_fail".
No
on_success
string

setup

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

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
hostname
Specify the hostname of the GitHub instance to authenticate with.
No
github.com
string
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.
No
GITHUB_TOKEN
env_var_name
version
Specify the full semver versioned tag to use. Default to latest.
No
latest
string
when
Specify when to run this command. Options are "on_success", "always" or "on_fail".
No
on_success
string

Orb Source

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 # This code is licensed from CircleCI to the user under the MIT license. # See here for details: https://circleci.com/developer/orbs/licensing version: 2.1 description: | Manage your GitHub projects in your CI pipeline with the GitHub CLI orb integration. display: home_url: https://cli.github.com/manual/ source_url: https://github.com/CircleCI-Public/github-cli-orb commands: clone: description: | 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. parameters: branch: default: "" description: Branch to checkout. Value defaults to empty, which will clone the default branch. type: string dir: default: . description: Select the path to clone into. By default the current path will be selected, which is dictated by the job's "working_directory". type: string hostname: default: github.com description: Specify the hostname of the GitHub instance to authenticate with. type: string repo: default: $CIRCLE_REPOSITORY_URL description: Enter either the name of the repository or the full repository URL. Will default to the current project. type: string when: default: on_success description: Specify when to run this command. Options are "on_success", "always" or "on_fail". type: string steps: - run: command: |+ #!/bin/bash # Ensure known hosts are entered. Required for Docker. mkdir -p ~/.ssh ssh-keyscan -t rsa "$PARAM_GH_HOSTNAME" >> ~/.ssh/known_hosts PARAM_GITHUB_REPO_EXPANDED="$(eval echo "$PARAM_GH_REPO")" if [ -n "$PARAM_BRANCH" ]; then gh repo clone "$PARAM_GITHUB_REPO_EXPANDED" "$PARAM_GH_DIR" -- "--branch=$PARAM_BRANCH" else gh repo clone "$PARAM_GITHUB_REPO_EXPANDED" "$PARAM_GH_DIR" fi environment: PARAM_BRANCH: <<parameters.branch>> PARAM_GH_DIR: <<parameters.dir>> PARAM_GH_HOSTNAME: <<parameters.hostname>> PARAM_GH_REPO: <<parameters.repo>> name: Cloning repository when: <<parameters.when>> install: description: | 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. parameters: version: default: latest description: Specify the full semver versioned tag to use. Default to latest. type: string when: default: on_success description: Specify when to run this command. Options are "on_success", "always" or "on_fail". type: string steps: - run: command: "#!/usr/bin/env bash\n\nset_sudo() {\n if [[ $EUID == 0 ]]; then \n echo \"\"\n else \n echo \"sudo\"\n fi\n}\n\n# Function to check if a version is greater than or equal to a given version\nversion_ge() {\n test \"$(echo \"$@\" | tr \" \" \"\\n\" | sort -rV | head -n 1)\" == \"$1\"\n}\n\n# Function to check if a version is less than or equal to a given version\nversion_le() {\n test \"$(echo \"$@\" | tr \" \" \"\\n\" | sort -V | head -n 1)\" == \"$1\"\n}\n\ndetect_platform() {\n case \"$(uname -s)-$(uname -m)\" in\n \"Darwin-x86_64\") echo \"macos_amd64\" ;;\n \"Darwin-arm64\") echo \"macos_arm64\" ;;\n \"Linux-x86_64\") echo \"linux_amd64\" ;;\n \"Linux-aarch64\") echo \"linux_arm64\" ;;\n *) echo \"unsupported\" ;;\n esac\n}\n\ndownload_gh_cli() {\n local platform=$1\n local file_extension=$2\n if [ \"$PARAM_GH_CLI_VERSION\" = \"latest\" ]; then\n LATEST_TAG=$(curl url -s https://api.github.com/repos/cli/cli/releases/latest | jq -r '.tag_name')\n PARAM_GH_CLI_VERSION=\"${LATEST_TAG#v}\"\n fi\n local download_url=\"https://github.com/cli/cli/releases/download/v${PARAM_GH_CLI_VERSION}/gh_${PARAM_GH_CLI_VERSION}_${platform}.${file_extension}\"\n echo \"Downloading the GitHub CLI from \\\"$download_url\\\"...\"\n\n if ! curl -sSL \"$download_url\" -o \"gh-cli.$file_extension\"; then\n echo \"Failed to download GH CLI from $download_url\" >&2\n return 1\n fi\n}\n\ninstall_gh_cli() {\n local platform=$1\n local file_extension=$2\n local file_path=\"gh-cli.$file_extension\"\n\n if [ ! -f \"$file_path\" ]; then\n echo \"Downloaded file $file_path does not exist.\" >&2\n return 1\n fi\n\n echo \"Installing the GitHub CLI...\"\n if [ \"$platform\" == \"linux_amd64\" ]; then \n set -x; $sudo apt install --yes ./\"$file_path\"; set +x\n else\n set -x; $sudo tar -xf ./\"$file_path\" -C /usr/local/ --strip-components=1; set +x\n fi\n}\n\nsudo=$(set_sudo)\n\n# Check for required commands\nfor cmd in curl tar; do\n if ! command -v \"$cmd\" &>/dev/null; then\n echo \"Error: $cmd is required. Please install it and try again.\" >&2\n exit 1\n fi\ndone\n\n# Verify if the CLI is already installed. Exit if it is.\nif command -v gh >/dev/null 2>&1; then\n echo \"GH CLI is already installed.\"\n exit 0\nfi\n\n# If the GH CLI version is less than or equal to 2.24.0 on macOS ARM then exit\n# Apple Silicon support was added in 2.25.0 (https://github.com/cli/cli/releases/tag/v2.25.0)\nif [[ \"$platform\" == \"macos_arm\" ]] && version_le \"$PARAM_GH_CLI_VERSION\" \"2.24.0\"; then\n echo \"You are trying to install version $PARAM_GH_CLI_VERSION. macOS ARM support was added in version 2.25.0, please specify a newer version.\"\n exit 1\nfi\n\nplatform=$(detect_platform)\nif [ \"$platform\" == \"unsupported\" ]; then\n echo \"$(uname -a)-$(uname -m) is not supported. If you believe it should be, please consider opening an issue.\"\n exit 1\nfi\n\n# Determine file extension\n# macOS releases after 2.28.0 adopted `.zip` (https://github.com/cli/cli/releases/tag/v2.28.0)\nfile_extension=\"tar.gz\"\nif [[ \"$platform\" == macos_* ]] && version_ge \"$PARAM_GH_CLI_VERSION\" \"2.28.0\"; then\n file_extension=\"zip\"\nelif [[ \"$platform\" == \"linux_amd64\" ]]; then\n file_extension=\"deb\"\nfi\n\n# Download and install GH CLI\nif ! download_gh_cli \"$platform\" \"$file_extension\"; then\n echo \"Failed to download the GH CLI.\"\n exit 1\nfi\n\nif ! install_gh_cli \"$platform\" \"$file_extension\"; then\n echo \"Failed to install the GH CLI.\"\n exit 1\nfi\n\n# Clean up\nif ! rm \"gh-cli.$file_extension\"; then\n echo \"Failed to remove the downloaded file.\"\nfi\n\n# Verify installation\nif ! command -v gh >/dev/null 2>&1; then\n echo \"Something went wrong installing the GH CLI. Please try again or open an issue.\"\n exit 1\nelse\n gh --version\nfi\n" environment: PARAM_GH_CLI_VERSION: <<parameters.version>> name: Install GH CLI v<<parameters.version>> when: <<parameters.when>> setup: description: Install and authenticate with the gh cli. This command should be run before invoking the gh cli. parameters: hostname: default: github.com description: Specify the hostname of the GitHub instance to authenticate with. type: string token: default: GITHUB_TOKEN description: | 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. type: env_var_name version: default: latest description: Specify the full semver versioned tag to use. Default to latest. type: string when: default: on_success description: Specify when to run this command. Options are "on_success", "always" or "on_fail". type: string steps: - install: version: <<parameters.version>> when: <<parameters.when>> - run: command: | #!/bin/bash # Get auth token [ -z "${!PARAM_GH_TOKEN}" ] && echo "A GitHub token must be supplied. Check the \"token\" parameter." && exit 1 if [[ "${PARAM_GH_HOSTNAME}" == "github.com" ]]; then export GITHUB_TOKEN=${!PARAM_GH_TOKEN} echo "export GITHUB_TOKEN=\"${GITHUB_TOKEN}\"" >> "$BASH_ENV" else export GH_ENTERPRISE_TOKEN=${!PARAM_GH_TOKEN} echo "export GH_ENTERPRISE_TOKEN=\"${GH_ENTERPRISE_TOKEN}\"" >> "$BASH_ENV" export GH_HOST=${PARAM_GH_HOSTNAME} echo "export GH_HOST=\"${PARAM_GH_HOSTNAME}\"" >> "$BASH_ENV" fi # Setup git with GH CLI echo echo "Setting up git with GH CLI" gh auth setup-git --hostname "$PARAM_GH_HOSTNAME" echo echo "Viewing authentication GH authentication status" gh auth status || echo "Viewing auth status is unavailable without proper scope." # Configure echo echo "Disabling interactive prompts for GH CLI" gh config set prompt disabled environment: PARAM_GH_HOSTNAME: <<parameters.hostname>> PARAM_GH_TOKEN: <<parameters.token>> name: Configure GH CLI v<<parameters.version>> when: <<parameters.when>> jobs: pr-merge: description: | Merge pull request to target branch. See more at https://cli.github.com/manual/gh_pr_merge. This requires write:discussion permissions. docker: - image: cimg/base:stable parameters: additional_args: default: "" description: Enter any additional arguments to pass to the `gh pr merge` command (e.g. --squash) type: string branch: default: $CIRCLE_BRANCH description: Enter PR number, branch or URL to merge. Without an argument, the pull request that belongs to the current branch is selected type: string hostname: default: github.com description: | Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance. type: string repo: default: $CIRCLE_REPOSITORY_URL description: Enter either the name of the repository or the full repository URL. Will default to the current project. type: string token: default: GITHUB_TOKEN description: | 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. type: env_var_name version: default: 2.20.2 description: Specify the full semver versioned tag to use for the GitHub CLI installation. type: string resource_class: small steps: - install: version: <<parameters.version>> - run: command: | #!/bin/bash branch="$(eval printf '%s' "$ORB_EVAL_BRANCH")" readarray -t additional_args < <(eval "set -- $ORB_EVAL_ADDITIONAL_ARGS; printf '%s\n' \"\$@\"") hostname="$(eval printf '%s' "$ORB_EVAL_HOSTNAME")" repo="$(eval printf '%s' "$ORB_EVAL_REPO")" token="${!ORB_ENV_TOKEN}" [ -z "$token" ] && { printf >&2 '%s\n' "A GitHub token must be supplied" "Check the \"token\" parameter." exit 1 } [ -z "$branch" ] && { printf >&2 '%s\n' "A target branch must be supplied" "Check the \"branch\" parameter." exit 1 } printf '%s\n' "export GITHUB_TOKEN=$token" >>"$BASH_ENV" [ -n "$hostname" ] && printf '%s\n' "export GITHUB_HOSTNAME=$hostname" >>"$BASH_ENV" [ -n "$repo" ] && repo="-R $repo" set -x # shellcheck disable=SC2086 gh pr merge \ $branch $repo \ "${additional_args[@]}" set +x environment: ORB_ENV_TOKEN: <<parameters.token>> ORB_EVAL_ADDITIONAL_ARGS: <<parameters.additional_args>> ORB_EVAL_BRANCH: <<parameters.branch>> ORB_EVAL_HOSTNAME: <<parameters.hostname>> ORB_EVAL_REPO: <<parameters.repo>> name: Merging PR to target branch release: description: | 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. docker: - image: cimg/base:stable parameters: additional_args: default: "" description: | 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 type: string clone: default: true description: Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo. type: boolean dir: default: . description: | 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. type: string draft: default: false description: Save the release as a draft instead of publishing it. type: boolean files: default: "" description: 'To include a subset of your repository''s files in the release, enter the file glob here. (e.g. ./dist/*.tgz) ' type: string hostname: default: github.com description: Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance. type: string notes-file: default: "" description: 'Path to file containing release notes (e.g.: ./changelog.md). ' type: string prerelease: default: false description: Mark the release as a prerelease. type: boolean tag: description: 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. type: string title: default: "" description: 'Include a release title. ' type: string token: default: GITHUB_TOKEN description: | 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. type: env_var_name version: default: latest description: Specify the full semver versioned tag to use for the GitHub CLI installation. Default to latest. type: string resource_class: small steps: - setup: hostname: <<parameters.hostname>> token: <<parameters.token>> version: <<parameters.version>> - when: condition: <<parameters.clone>> steps: - clone: dir: <<parameters.dir>> hostname: <<parameters.hostname>> - run: command: "#!/bin/bash\n# Get auth token\nset -x\ncd \"$PARAM_DIR\" || exit\nexport GITHUB_TOKEN=${!PARAM_GH_TOKEN}\n[ -z \"$GITHUB_TOKEN\" ] && echo \"A GitHub token must be supplied. Check the \\\"token\\\" parameter.\" && exit 1\necho \"export GITHUB_TOKEN=\\\"${GITHUB_TOKEN}\\\"\" >>\"$BASH_ENV\"\n\n# Get hostname if set\nif [ \"$PARAM_GH_HOSTNAME\" == 1 ]; then\n\texport GITHUB_HOSTNAME=${!PARAM_GH_HOSTNAME}\n\techo \"export GITHUB_HOSTNAME=\\\"${PARAM_GH_HOSTNAME}\\\"\" >>\"$BASH_ENV\"\nfi\n\nif [ -n \"$PARAM_GH_ARGS\" ]; then\n\tset -- \"$@\" \"$PARAM_GH_ARGS\"\nfi\nif [ \"$PARAM_GH_DRAFT\" == 1 ]; then\n\tset -- \"$@\" --draft\nfi\nif [ \"$PARAM_GH_PRERELEASE\" == 1 ]; then\n\tset -- \"$@\" --prerelease\nfi\nif [ -n \"$PARAM_GH_NOTES\" ]; then\n\tset -- \"$@\" --notes-file \"$PARAM_GH_NOTES\"\nfi\nif [ -n \"$PARAM_GH_TITLE\" ]; then\n\tset -- \"$@\" --title \"$PARAM_GH_TITLE\"\nfi\nif [ -n \"$PARAM_GH_FILES\" ]; then\n\tset -- \"$@\" \"$PARAM_GH_FILES\"\nfi\n \nset -- \"$@\" --repo \"$(git config --get remote.origin.url)\"\n\n# shellcheck disable=SC2086,SC2068\ngh release create \\\n \"$PARAM_GH_TAG\" \\\n $@\n" environment: PARAM_DIR: <<parameters.dir>> PARAM_GH_ARGS: <<parameters.additional_args>> PARAM_GH_DRAFT: <<parameters.draft>> PARAM_GH_FILES: <<parameters.files>> PARAM_GH_HOSTNAME: <<parameters.hostname>> PARAM_GH_NOTES: <<parameters.notes-file>> PARAM_GH_PRERELEASE: <<parameters.prerelease>> PARAM_GH_TAG: <<parameters.tag>> PARAM_GH_TITLE: <<parameters.title>> PARAM_GH_TOKEN: <<parameters.token>> name: Creating a <<#parameters.draft>><<parameters.draft>> <</parameters.draft>>GitHub Release upload: description: | 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. docker: - image: cimg/base:stable parameters: additional_args: default: "" description: Enter any additional arguments to pass to the `gh release upload` command (e.g. --clobber) type: string clone: default: true description: Whether or not clone the repo. Defaults to true. Set to false if you already cloned the repo. type: boolean dir: default: . description: | 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. type: string files: description: 'To include a subset of your repository''s files in the release, enter the file glob here. (e.g. ./dist/*.tgz) ' type: string hostname: default: github.com description: | Specify the hostname of the GitHub instance to authenticate with. Set this to connect to your GitHub Enterprise instance. type: string tag: default: $CIRCLE_TAG description: | Specify the tag which the asset files will be uploaded to. A GitHub Release matching the tag must already exist. type: string token: default: GITHUB_TOKEN description: | 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. type: env_var_name version: default: 2.20.2 description: Specify the full semver versioned tag to use for the GitHub CLI installation. type: string resource_class: small steps: - install: version: <<parameters.version>> - when: condition: <<parameters.clone>> steps: - clone: dir: <<parameters.dir>> hostname: <<parameters.hostname>> - run: command: | #!/usr/bin/env bash cd "$PARAM_DIR" || exit additional_args="$(eval printf '%s\\n' "$ORB_EVAL_ADDITIONAL_ARGS")" files="$(eval printf '%s\\n' "$ORB_EVAL_FILES")" hostname="$(eval printf '%s' "$ORB_EVAL_HOSTNAME")" tag="$(eval printf '%s' "$ORB_EVAL_TAG")" token="${!ORB_ENV_TOKEN}" [ -z "$token" ] && { printf >&2 '%s\n' "A GitHub token must be supplied" "Check the \"token\" parameter." exit 1 } printf '%s\n' "export GITHUB_TOKEN=$token" >>"$BASH_ENV" [ -n "$hostname" ] && printf '%s\n' "export GITHUB_HOSTNAME=$hostname" >>"$BASH_ENV" set -x # shellcheck disable=SC2086 gh release upload \ "$tag" \ $files \ --repo "$(git config --get remote.origin.url)" \ $additional_args set +x environment: ORB_ENV_TOKEN: <<parameters.token>> ORB_EVAL_ADDITIONAL_ARGS: <<parameters.additional_args>> ORB_EVAL_FILES: <<parameters.files>> ORB_EVAL_HOSTNAME: <<parameters.hostname>> ORB_EVAL_TAG: <<parameters.tag>> PARAM_DIR: <<parameters.dir>> name: Uploading assets to GitHub Release examples: create_release: description: | 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. usage: version: "2.1" orbs: gh: circleci/github-cli@2.6 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: description: | 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`. usage: version: "2.1" orbs: gh: circleci/github-cli@2.6 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: description: | 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. usage: version: "2.1" orbs: gh: circleci/github-cli@2.6.0 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: description: | 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`. usage: version: "2.1" orbs: gh: circleci/github-cli@2.6 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
Developer Updates
Get tips to optimize your builds
Or join our research panel and give feedback
By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.