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.
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
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
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
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
Merge pull request to target branch. See more at https://cli.github.com/manual/gh_pr_merge. This requires write:discussion permissions.
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 |
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 | 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 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 | 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 |
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 | 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 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 | 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 |
Install and authenticate with the gh cli. This command should be run before invoking the gh cli.
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 |
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