Skip to content

Commit 95bd8c8

Browse files
Sarah Edwardsethanpalmmislavlecoursen
authored
[Aug 24, 2021] Top level CLI docs set (#20628)
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Co-authored-by: Mislav Marohnić <mislav@github.com> Co-authored-by: Laura Coursen <lecoursen@github.com>
1 parent 893a70b commit 95bd8c8

51 files changed

Lines changed: 892 additions & 178 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎content/actions/guides/index.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,6 @@ includeGuides:
7272
- /actions/guides/commenting-on-an-issue-when-a-label-is-added
7373
- /actions/guides/moving-assigned-issues-on-project-boards
7474
- /actions/guides/removing-a-label-when-a-card-is-added-to-a-project-board-column
75-
- /actions/guides/managing-github-actions-with-github-cli
7675
- /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/automating-dependabot-with-github-actions
7776
- /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot
7877
children:
@@ -109,6 +108,6 @@ children:
109108
- /commenting-on-an-issue-when-a-label-is-added
110109
- /moving-assigned-issues-on-project-boards
111110
- /removing-a-label-when-a-card-is-added-to-a-project-board-column
112-
- /managing-github-actions-with-github-cli
111+
- /using-github-cli-in-workflows
113112
---
114113

‎content/actions/guides/managing-github-actions-with-github-cli.md‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎content/actions/guides/using-github-cli-in-workflows.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Using GitHub CLI in workflows
3+
shortTitle: GitHub CLI in workflows
4+
intro: 'You can script with {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %} workflows.'
5+
versions:
6+
fpt: '*'
7+
ghes: '>=2.22'
8+
ghae: '*'
9+
topics:
10+
- CLI
11+
- Workflows
12+
type: how_to
13+
---
14+
15+
{% data reusables.cli.cli-learn-more %}
16+
17+
{% data variables.product.prodname_cli %} is preinstalled on all {% data variables.product.prodname_dotcom %}-hosted runners. For each step that uses {% data variables.product.prodname_cli %}, you must set an environment variable called `GITHUB_TOKEN` to a token with the required scopes.
18+
19+
You can execute any {% data variables.product.prodname_cli %} command. For example, this workflow uses the `gh issue comment` subcommand to add a comment when an issue is opened.
20+
21+
```yaml{:copy}
22+
name: Comment when opened
23+
on:
24+
issues:
25+
types:
26+
- opened
27+
jobs:
28+
comment:
29+
runs-on: ubuntu-latest
30+
steps:
31+
- run: gh issue comment $ISSUE --body "Thank you for opening this issue!"
32+
env:
33+
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
34+
ISSUE: {% raw %}${{ github.event.issue.html_url }}{% endraw %}
35+
```
36+
37+
You can also execute API calls through {% data variables.product.prodname_cli %}. For example, this workflow first uses the `gh api` subcommand to query the GraphQL API and parse the result. Then it stores the result in an environment variable that it can access in a later step. In the second step, it uses the `gh issue create` subcommand to create an issue containing the information from the first step.
38+
39+
```yaml{:copy}
40+
name: Report remaining open issues
41+
on:
42+
schedule:
43+
# Daily at 8:20 UTC
44+
- cron: '20 8 * * *'
45+
jobs:
46+
track_pr:
47+
runs-on: ubuntu-latest
48+
steps:
49+
- run: |
50+
numOpenIssues="$(gh api graphql -F owner=$OWNER -F name=$REPO -f query='
51+
query($name: String!, $owner: String!) {
52+
repository(owner: $owner, name: $name) {
53+
issues(states:OPEN){
54+
totalCount
55+
}
56+
}
57+
}
58+
' --jq '.data.repository.issues.totalCount')"
59+
60+
echo 'NUM_OPEN_ISSUES='$numOpenIssues >> $GITHUB_ENV
61+
env:
62+
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
63+
OWNER: {% raw %}${{ github.repository_owner }}{% endraw %}
64+
REPO: {% raw %}${{ github.event.repository.name }}{% endraw %}
65+
- run: |
66+
gh issue create --title "Issue report" --body "$NUM_OPEN_ISSUES issues remaining" --repo $GITHUB_REPOSITORY
67+
env:
68+
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
69+
```

‎content/actions/managing-workflow-runs/disabling-and-enabling-a-workflow.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Temporarily disabling a workflow can be useful in many scenarios. These are a fe
3030

3131
You can also disable and enable a workflow using the REST API. For more information, see the "[Actions REST API](/rest/reference/actions#workflows)."
3232

33-
### Disabling a workflow
33+
## Disabling a workflow
3434

3535
{% include tool-switcher %}
3636

@@ -51,9 +51,7 @@ The disabled workflow is marked {% octicon "stop" aria-label="The stop icon" %}
5151

5252
{% cli %}
5353

54-
{% data reusables.cli.download-cli %}
55-
56-
{% data reusables.actions.actions-cli %}
54+
{% data reusables.cli.cli-learn-more %}
5755

5856
To disable a workflow, use the `workflow disable` subcommand. Replace `workflow` with either the name, ID, or file name of the workflow you want to disable. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow.
5957

@@ -63,7 +61,7 @@ gh workflow disable <em>workflow</em>
6361

6462
{% endcli %}
6563

66-
### Enabling a workflow
64+
## Enabling a workflow
6765

6866
{% include tool-switcher %}
6967

@@ -82,8 +80,6 @@ You can re-enable a workflow that was previously disabled.
8280

8381
{% cli %}
8482

85-
{% data reusables.actions.actions-cli %}
86-
8783
To enable a workflow, use the `workflow enable` subcommand. Replace `workflow` with either the name, ID, or file name of the workflow you want to enable. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow.
8884

8985
```shell

‎content/actions/managing-workflow-runs/downloading-workflow-artifacts.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,7 @@ shortTitle: Download workflow artifacts
3737

3838
{% cli %}
3939

40-
{% data reusables.cli.download-cli %}
41-
42-
{% data reusables.actions.actions-cli %}
40+
{% data reusables.cli.cli-learn-more %}
4341

4442
{% data variables.product.prodname_cli %} will download each artifact into separate directories based on the artifact name. If only a single artifact is specified, it will be extracted into the current directory.
4543

‎content/actions/managing-workflow-runs/manually-running-a-workflow.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ To run a workflow manually, the workflow must be configured to run on the `workf
1919

2020
{% data reusables.repositories.permissions-statement-write %}
2121

22-
### Running a workflow
22+
## Running a workflow
2323

2424
{% include tool-switcher %}
2525

@@ -38,9 +38,7 @@ To run a workflow manually, the workflow must be configured to run on the `workf
3838

3939
{% cli %}
4040

41-
{% data reusables.cli.download-cli %}
42-
43-
{% data reusables.actions.actions-cli %}
41+
{% data reusables.cli.cli-learn-more %}
4442

4543
To run a workflow, use the `workflow run` subcommand. Replace the `workflow` parameter with either the name, ID, or file name of the workflow you want to run. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow.
4644

@@ -74,7 +72,7 @@ gh run watch
7472

7573
{% endcli %}
7674

77-
### Running a workflow using the REST API
75+
## Running a workflow using the REST API
7876

7977
When using the REST API, you configure the `inputs` and `ref` as request body parameters. If the inputs are omitted, the default values defined in the workflow file are used.
8078

‎content/actions/managing-workflow-runs/re-running-a-workflow.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,7 @@ Re-running a workflow uses the same `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (
2929

3030
{% cli %}
3131

32-
{% data reusables.cli.download-cli %}
33-
34-
{% data reusables.actions.actions-cli %}
32+
{% data reusables.cli.cli-learn-more %}
3533

3634
To re-run a failed workflow run, use the `run rerun` subcommand. Replace `run-id` with the ID of the failed run that you want to re-run. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent failed run.
3735

‎content/actions/managing-workflow-runs/using-workflow-run-logs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ After the logs have been deleted, the **Delete all logs** button is removed to i
112112

113113
## Viewing logs with {% data variables.product.prodname_cli %}
114114

115-
{% data reusables.actions.actions-cli %}
115+
{% data reusables.cli.cli-learn-more %}
116116

117117
To view the log for a specific job, use the `run view` subcommand. Replace `run-id` with the ID of run that you want to view logs for. {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a job from the run. If you don't specify `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run, and then returns another interactive menu for you to choose a job from the run.
118118

‎content/actions/managing-workflow-runs/viewing-workflow-run-history.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,7 @@ shortTitle: View workflow run history
2828

2929
{% cli %}
3030

31-
{% data reusables.cli.download-cli %}
32-
33-
{% data reusables.actions.actions-cli %}
31+
{% data reusables.cli.cli-learn-more %}
3432

3533
### Viewing recent workflow runs
3634

‎content/actions/reference/encrypted-secrets.md‎

Lines changed: 100 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,20 @@ You can also manage secrets using the REST API. For more information, see "[Secr
5858

5959
When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/developers/overview/managing-deploy-keys#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token (PAT), select the fewest scopes necessary.
6060

61+
{% note %}
62+
63+
**Note:** You can use the REST API to manage secrets. For more information, see "[{% data variables.product.prodname_actions %} secrets API](/rest/reference/actions#secrets)."
64+
65+
{% endnote %}
66+
6167
## Creating encrypted secrets for a repository
6268

6369
{% data reusables.github-actions.permissions-statement-secrets-repository %}
6470

71+
{% include tool-switcher %}
72+
73+
{% webui %}
74+
6575
{% data reusables.repositories.navigate-to-repo %}
6676
{% data reusables.repositories.sidebar-settings %}
6777
{% data reusables.github-actions.sidebar-secret %}
@@ -72,26 +82,65 @@ When generating credentials, we recommend that you grant the minimum permissions
7282

7383
If your repository {% ifversion fpt or ghes > 3.0 or ghae %}has environment secrets or {% endif %}can access secrets from the parent organization, then those secrets are also listed on this page.
7484

75-
{% note %}
85+
{% endwebui %}
7686

77-
**Note:** Users with collaborator access can use the REST API to manage secrets for a repository. For more information, see "[{% data variables.product.prodname_actions %} secrets API](/rest/reference/actions#secrets)."
87+
{% cli %}
7888

79-
{% endnote %}
89+
{% data reusables.cli.cli-learn-more %}
90+
91+
To add a repository secret, use the `gh secret set` subcommand. Replace `secret-name` with the name of your secret.
92+
93+
```shell
94+
gh secret set <em>secret-name</em>
95+
```
96+
97+
The CLI will prompt you to enter a secret value. Alternatively, you can read the value of the secret from a file.
98+
99+
```shell
100+
gh secret set <em>secret-name</em> < secret.txt
101+
```
102+
103+
To list all secrets for the repository, use the `gh secret list` subcommand.
104+
105+
{% endcli %}
80106

81107
{% ifversion fpt or ghes > 3.0 or ghae %}
82108

83109
## Creating encrypted secrets for an environment
84110

85111
{% data reusables.github-actions.permissions-statement-secrets-environment %}
86112

113+
{% include tool-switcher %}
114+
115+
{% webui %}
116+
87117
{% data reusables.repositories.navigate-to-repo %}
88118
{% data reusables.repositories.sidebar-settings %}
89119
{% data reusables.github-actions.sidebar-environment %}
90120
1. Click on the environment that you want to add a secret to.
91-
1. Under **Environment secrets**, click **Add secret**.
92-
1. Type a name for your secret in the **Name** input box.
93-
1. Enter the value for your secret.
94-
1. Click **Add secret**.
121+
2. Under **Environment secrets**, click **Add secret**.
122+
3. Type a name for your secret in the **Name** input box.
123+
4. Enter the value for your secret.
124+
5. Click **Add secret**.
125+
126+
{% endwebui %}
127+
128+
{% cli %}
129+
130+
To add a secret for an environment, use the `gh secret set` subcommand with the `--env` or `-e` flag followed by the environment name.
131+
132+
```shell
133+
gh secret set --env <em>environment-name</em> <em>secret-name</em>
134+
```
135+
136+
To list all secrets for an environment, use the `gh secret list` subcommand with the `--env` or `-e` flag followed by the environment name.
137+
138+
```shell
139+
gh secret list --env <em>environment-name</em>
140+
```
141+
142+
{% endcli %}
143+
95144
{% endif %}
96145

97146
## Creating encrypted secrets for an organization
@@ -100,6 +149,10 @@ When creating a secret in an organization, you can use a policy to limit which r
100149

101150
{% data reusables.github-actions.permissions-statement-secrets-organization %}
102151

152+
{% include tool-switcher %}
153+
154+
{% webui %}
155+
103156
{% data reusables.organizations.navigate-to-org %}
104157
{% data reusables.organizations.org_settings %}
105158
{% data reusables.github-actions.sidebar-secret %}
@@ -109,6 +162,46 @@ When creating a secret in an organization, you can use a policy to limit which r
109162
1. From the **Repository access** dropdown list, choose an access policy.
110163
1. Click **Add secret**.
111164

165+
{% endwebui %}
166+
167+
{% cli %}
168+
169+
{% note %}
170+
171+
**Note:** By default, {% data variables.product.prodname_cli %} authenticates with the `repo` and `read:org` scopes. To manage organization secrets, you must additionally authorize the `admin:org` scope.
172+
173+
```
174+
gh auth login --scopes "admin:org"
175+
```
176+
177+
{% endnote %}
178+
179+
To add a secret for an organization, use the `gh secret set` subcommand with the `--org` or `-o` flag followed by the organization name.
180+
181+
```shell
182+
gh secret set --org <em>organization-name</em> <em>secret-name</em>
183+
```
184+
185+
By default, the secret is only available to private repositories. To specify that the secret should be available to all repositories within the organization, use the `--visibility` or `-v` flag.
186+
187+
```shell
188+
gh secret set --org <em>organization-name</em> <em>secret-name</em> --visibility all
189+
```
190+
191+
To specify that the secret should be available to selected repositories within the organization, use the `--repos` or `-r` flag.
192+
193+
```shell
194+
gh secret set --org <em>organization-name</em> <em>secret-name</em> --repos <em>repo-name-1</em>,<em>repo-name-2</em>"
195+
```
196+
197+
To list all secrets for an organization, use the `gh secret list` subcommand with the `--org` or `-o` flag followed by the organization name.
198+
199+
```shell
200+
gh secret list --org <em>organization-name</em>
201+
```
202+
203+
{% endcli %}
204+
112205
## Reviewing access to organization-level secrets
113206
114207
You can check which access policies are being applied to a secret in your organization.

0 commit comments

Comments
 (0)