Skip to content

Commit d53e41a

Browse files
Sarah EdwardsMartin Lopes
Sarah Edwards
and
Martin Lopes
authored
[Apr 14] cli for actions (#18683)
Co-authored-by: Martin Lopes <martin389@github.com>
1 parent 7da1d19 commit d53e41a

14 files changed

Lines changed: 242 additions & 5 deletions

‎content/actions/guides/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ includeGuides:
7070
- /actions/guides/commenting-on-an-issue-when-a-label-is-added
7171
- /actions/guides/moving-assigned-issues-on-project-boards
7272
- /actions/guides/removing-a-label-when-a-card-is-added-to-a-project-board-column
73+
- /actions/guides/managing-github-actions-with-github-cli
7374

7475
---
7576
<!-- {% link_in_list /about-continuous-integration %} -->
@@ -104,3 +105,4 @@ includeGuides:
104105
<!-- {% link_in_list /commenting-on-an-issue-when-a-label-is-added %} -->
105106
<!-- {% link_in_list /moving-assigned-issues-on-project-boards %} -->
106107
<!-- {% link_in_list /removing-a-label-when-a-card-is-added-to-a-project-board-column %} -->
108+
<!-- {% link_in_list /managing-github-actions-with-github-cli %} -->

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Managing GitHub Actions with GitHub CLI
3+
intro: 'You can use {% data variables.product.prodname_cli %} to interact with {% data variables.product.prodname_actions %}.'
4+
product: '{% data reusables.gated-features.actions %}'
5+
versions:
6+
free-pro-team: '*'
7+
enterprise-server: '>=2.22'
8+
github-ae: '*'
9+
type: 'overview'
10+
topics:
11+
- 'Workflows'
12+
---
13+
14+
{% data reusables.actions.enterprise-beta %}
15+
{% data reusables.actions.enterprise-github-hosted-runners %}
16+
{% data reusables.actions.ae-beta %}
17+
18+
### Setting up {% data variables.product.prodname_cli %}
19+
20+
{% data reusables.cli.download-update-cli %} {% data reusables.cli.actions-cli-version %} {% data reusables.cli.cli-manual %}
21+
22+
{% data reusables.cli.cli-auth %}
23+
24+
{% data reusables.cli.cli-repo %}
25+
26+
### Managing {% data variables.product.prodname_actions %} with {% data variables.product.prodname_cli %}
27+
28+
To view all available commands related to {% data variables.product.prodname_actions %}, run `gh actions`.
29+
30+
For more information on using commands in specific scenarios, see the following procedures:
31+
32+
- "[Re-running a workflow](/actions/managing-workflow-runs/re-running-a-workflow#re-run-a-workflow-through-github-cli)"
33+
- "[Manually running a workflow](/actions/managing-workflow-runs/manually-running-a-workflow#running-a-workflow-using-github-cli)"
34+
- "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts#download-artifacts-through-github-cli)"
35+
- "[Using workflow run logs](/actions/managing-workflow-runs/using-workflow-run-logs#viewing-logs-through-github-cli)"
36+
- "[Viewing workflow run history](/actions/managing-workflow-runs/viewing-workflow-run-history#viewing-workflow-run-history-with-github-cli)"
37+
- "[Disabling and enabling a workflow](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow#disabling-and-enabling-workflows-through-github-cli)"

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

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Disabling and enabling a workflow
3-
intro: 'You can disable and re-enable a workflow using {% data variables.product.prodname_dotcom %} or the REST API.'
3+
intro: 'You can disable and re-enable a workflow using the {% data variables.product.prodname_dotcom %} UI, the REST API, or {% data variables.product.prodname_cli %}.'
44
product: '{% data reusables.gated-features.actions %}'
55
versions:
66
free-pro-team: '*'
@@ -12,7 +12,7 @@ versions:
1212
{% data reusables.actions.enterprise-github-hosted-runners %}
1313
{% data reusables.actions.ae-beta %}
1414

15-
Disabling a workflow allows you to stop a workflow from being triggered without having to delete the file from the repo. You can easily re-enable the workflow again on {% data variables.product.prodname_dotcom %}. You can also disable and enable a workflow using the REST API. For more information, see the "[Actions REST API](/rest/reference/actions#workflows)."
15+
Disabling a workflow allows you to stop a workflow from being triggered without having to delete the file from the repo. You can easily re-enable the workflow again on {% data variables.product.prodname_dotcom %}.
1616

1717
Temporarily disabling a workflow can be useful in many scenarios. These are a few examples where disabling a workflow might be helpful:
1818

@@ -27,7 +27,9 @@ Temporarily disabling a workflow can be useful in many scenarios. These are a fe
2727

2828
{% endwarning %}
2929

30-
### Disabling a workflow
30+
### Disabling and enabling workflows with the {% data variables.product.prodname_dotcom %} UI
31+
32+
#### Disabling a workflow
3133

3234
You can manually disable a workflow so that it won't execute any workflow runs. A disabled workflow is not deleted, and can be re-enabled.
3335

@@ -42,7 +44,7 @@ You can manually disable a workflow so that it won't execute any workflow runs.
4244
The disabled workflow is marked {% octicon "stop" aria-label="The stop icon" %} to indicate its status.
4345
![actions list disabled workflow](/assets/images/help/repository/actions-find-disabled-workflow.png)
4446

45-
### Enabling a workflow
47+
#### Enabling a workflow
4648

4749
You can re-enable a workflow that was previously disabled.
4850

@@ -52,3 +54,23 @@ You can re-enable a workflow that was previously disabled.
5254
![actions select disabled workflow](/assets/images/help/repository/actions-select-disabled-workflow.png)
5355
1. Click **Enable workflow**.
5456
![actions enable workflow](/assets/images/help/repository/actions-enable-workflow.png)
57+
58+
### Disabling and enabling workflows with {% data variables.product.prodname_cli %}
59+
60+
{% data reusables.actions.actions-cli %}
61+
62+
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.
63+
64+
```shell
65+
gh workflow disable <em>workflow</em>
66+
```
67+
68+
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.
69+
70+
```shell
71+
gh workflow enable <em>workflow</em>
72+
```
73+
74+
### Disabling and enabling workflows through the REST API
75+
76+
You can also disable and enable a workflow using the REST API. For more information, see the "[Actions REST API](/rest/reference/actions#workflows)."

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ versions:
1515
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %} By default, {% data variables.product.product_name %} stores build logs and artifacts for 90 days, and you can customize this retention period, depending on the type of repository. For more information, see "[Configuring the retention period for GitHub Actions artifacts and logs in your repository](/github/administering-a-repository/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository)."{% endif %}
1616
{% if currentVersion == "enterprise-server@2.22" %} {% data variables.product.product_name %} stores full build logs and artifacts for 90 days.{% endif %}
1717

18+
### Download artifacts with the {% data variables.product.prodname_dotcom %} UI
19+
1820
{% data reusables.repositories.permissions-statement-read %}
1921

2022
{% data reusables.repositories.navigate-to-repo %}
@@ -27,3 +29,33 @@ versions:
2729
{% else %}
2830
![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png)
2931
{% endif %}
32+
33+
### Download artifacts with {% data variables.product.prodname_cli %}
34+
35+
{% data reusables.actions.actions-cli %}
36+
37+
{% 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.
38+
39+
To download all artifacts generated by a workflow run, use the `run download` subcommand. Replace `run-id` with the ID of the run that you want to download artifacts from. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run.
40+
41+
```shell
42+
gh run download <em>run-id</em>
43+
```
44+
45+
To download a specific artifact from a run, use the `run download` subcommand. Replace `run-id` with the ID of the run that you want to download artifacts from. Replace `artifact-name` with the name of the artifact that you want to download.
46+
47+
```shell
48+
gh run download <em>run-id</em> -n <em>artifact-name</em>
49+
```
50+
51+
You can specify more than one artifact.
52+
53+
```shell
54+
gh run download <em>run-id</em> -n <em>artifact-name-1</em> -n <em>artifact-name-2</em>
55+
```
56+
57+
To download specific artifacts across all runs in a repository, use the `run download` subcommand.
58+
59+
```shell
60+
gh run download -n <em>artifact-name-1</em> -n <em>artifact-name-2</em>
61+
```

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

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Manually running a workflow
3-
intro: 'When a workflow is configured to run on the `workflow_dispatch` event, you can run the workflow using the REST API or from the Actions tab on {% data variables.product.prodname_dotcom %}.'
3+
intro: 'When a workflow is configured to run on the `workflow_dispatch` event, you can run the workflow using the Actions tab on {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_cli %}, or the REST API.'
44
product: '{% data reusables.gated-features.actions %}'
55
versions:
66
free-pro-team: '*'
@@ -31,6 +31,40 @@ To trigger the `workflow_dispatch` event on {% data variables.product.prodname_d
3131
1. Select the branch where the workflow will run and type the input parameters used by the workflow. Click **Run workflow**.
3232
![actions manually run workflow](/assets/images/actions-manually-run-workflow.png)
3333

34+
### Running a workflow using {% data variables.product.prodname_cli %}
35+
36+
{% data reusables.actions.actions-cli %}
37+
38+
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.
39+
40+
```shell
41+
gh workflow run <em>workflow</em>
42+
```
43+
44+
If your workflow accepts inputs, {% data variables.product.prodname_cli %} will prompt you to enter them. Alternatively, you can use `-f` or `-F` to add an input in `key=value` format. Use `-F` to read from a file.
45+
46+
```shell
47+
gh workflow run greet.yml -f name=mona -f greeting=hello -F data=@myfile.txt
48+
```
49+
50+
You can also pass inputs as JSON by using standard input.
51+
52+
```shell
53+
echo '{"name":"mona", "greeting":"hello"}' | gh workflow run greet.yml --json
54+
```
55+
56+
To run a workflow on a branch other than the repository's default branch, use the `--ref` flag.
57+
58+
```shell
59+
gh workflow run <em>workflow</em> --ref <em>branch-name</em>
60+
```
61+
62+
To view the progress of the workflow run, use the `run watch` subcommand and select the run from the interactive list.
63+
64+
```shell
65+
gh run watch
66+
```
67+
3468
### Running a workflow using the REST API
3569

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

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,28 @@ versions:
1212
{% data reusables.actions.enterprise-github-hosted-runners %}
1313
{% data reusables.actions.ae-beta %}
1414

15+
### Re-run a workflow using the {% data variables.product.prodname_dotcom %} UI
16+
1517
{% data reusables.repositories.permissions-statement-write %}
1618

1719
{% data reusables.repositories.navigate-to-repo %}
1820
{% data reusables.repositories.actions-tab %}
1921
{% data reusables.repositories.navigate-to-workflow %}
2022
{% data reusables.repositories.view-run %}
2123
1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" or currentVersion == "github-ae@latest" %}![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down-updated.png){% else %}![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down.png){% endif %}
24+
25+
### Re-run a workflow using {% data variables.product.prodname_cli %}
26+
27+
{% data reusables.actions.actions-cli %}
28+
29+
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.
30+
31+
```shell
32+
gh run rerun <em>run-id</em>
33+
```
34+
35+
To view the progress of the workflow run, use the `run watch` subcommand and select the run from the interactive list.
36+
37+
```shell
38+
gh run watch
39+
```

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,31 @@ After deleting logs, the **Delete all logs** button is removed to indicate that
109109
![Delete all logs](/assets/images/help/repository/delete-all-logs.png)
110110
After the logs have been deleted, the **Delete all logs** button is removed to indicate that no log files remain in the workflow run.
111111
{% endif %}
112+
113+
### Viewing logs with {% data variables.product.prodname_cli %}
114+
115+
{% data reusables.actions.actions-cli %}
116+
117+
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.
118+
119+
```shell
120+
gh run view <em>run-id</em> --log
121+
```
122+
123+
You can also use the `--job` flag to specify a job ID. Replace `job-id` with the ID of the job that you want to view logs for.
124+
125+
```shell
126+
gh run view --job <em>job-id</em> --log
127+
```
128+
129+
You can use `grep` to search the log. For example, this command will return all log entries that contain the word `error`.
130+
131+
```shell
132+
gh run view --job <em>job-id</em> --log | grep error
133+
```
134+
135+
To filter the logs for any failed steps, use `--log-failed` instead of `--log`.
136+
137+
```shell
138+
gh run view --job <em>job-id</em> --log-failed
139+
```

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,67 @@ versions:
1212
{% data reusables.actions.enterprise-github-hosted-runners %}
1313
{% data reusables.actions.ae-beta %}
1414

15+
### Viewing workflow run history on {% data variables.product.prodname_dotcom %}
16+
1517
{% data reusables.repositories.permissions-statement-read %}
1618

1719
{% data reusables.repositories.navigate-to-repo %}
1820
{% data reusables.repositories.actions-tab %}
1921
{% data reusables.repositories.navigate-to-workflow %}
2022
{% data reusables.repositories.view-run %}
23+
24+
### Viewing workflow run history with {% data variables.product.prodname_cli %}
25+
26+
{% data reusables.actions.actions-cli %}
27+
28+
#### Viewing recent workflow runs
29+
30+
To list the recent workflow runs, use the `run list` subcommand.
31+
32+
```shell
33+
gh run list
34+
```
35+
36+
To specify the maximum number of runs to return, you can use the `-L` or `--limit` flag . The default is `10`.
37+
38+
```shell
39+
gh run list --limit 5
40+
```
41+
42+
To only return runs for the specified workflow, you can use the `-w` or `--workflow` flag. Replace `workflow` with either the workflow name, workflow ID, or workflow file name. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`.
43+
44+
```shell
45+
gh run list --workflow <em>workflow</em>
46+
```
47+
48+
#### Viewing details for a specific workflow run
49+
50+
To display details for a specific workflow run, use the `run view` subcommand. Replace `run-id` with the ID of the run that you want to view. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run.
51+
52+
```shell
53+
gh run view <em>run-id</em>
54+
```
55+
56+
To include job steps in the output, use the `-v` or `--verbose` flag.
57+
58+
```shell
59+
gh run view <em>run-id</em> --verbose
60+
```
61+
62+
To view details for a specific job in the run, use the `-j` or `--job` flag. Replace `job-id` with the ID of the job that you want to view.
63+
64+
```shell
65+
gh run view --job <em>job-id</em>
66+
```
67+
68+
To view the full log for a job, use the `--log` flag.
69+
70+
```shell
71+
gh run view --job <em>job-id</em> --log
72+
```
73+
74+
Use the `--exit-status` flag to exit with a non-zero status if the run failed. For example:
75+
76+
```shell
77+
gh run view 0451 --exit-status && echo "run pending or passed"
78+
```

‎data/reusables/actions/actions-cli.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
For information on setting up {% data variables.product.prodname_cli %}, see "[Managing GitHub Actions with GitHub CLI](/actions/guides/managing-github-actions-with-github-cli#setting-up-github-cli)."

‎data/reusables/cli/actions-cli-version.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
To access all of the {% data variables.product.prodname_actions %}-related commands, you must use version 1.9.0 or greater.

0 commit comments

Comments
 (0)