jprdonnelly/docs
1
0
Fork 0
mirror of synced 2026-01-05 12:07:35 -05:00
Code Issues Projects Releases Wiki Activity

Add first examples of Actions example library (#21282)

Browse Source 
Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>
This commit is contained in:
Martin Lopes
2022-05-30 14:28:14 +10:00
committed by GitHub
parent 09f6c10c71
commit 36c00a8d19
26 changed files with 1611 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
content/actions/examples/index.md Normal file
View File

@@ -0,0 +1,14 @@
---
title: Examples
shortTitle: Examples
intro: 'Example workflows that demonstrate the CI/CD features of {% data variables.product.prodname_actions %}.'
versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
children:
- using-scripts-to-test-your-code-on-a-runner
- using-the-github-cli-on-a-runner
- using-concurrency-expressions-and-a-test-matrix
---

658
content/actions/examples/using-concurrency-expressions-and-a-test-matrix.md Normal file
View File

@@ -0,0 +1,658 @@
---
title: Using concurrency, expressions, and a test matrix
shortTitle: Using concurrency, expressions, and a test matrix
intro: 'How to use advanced {% data variables.product.prodname_actions %} features for continuous integration (CI).'
versions:
fpt: '*'
ghes: '>= 3.5'
ghae: 'issue-4925'
ghec: '*'
showMiniToc: false
type: how_to
topics:
- Workflows
---
{% data reusables.actions.enterprise-github-hosted-runners %}
- [Example overview](#example-overview)
- [Features used in this example](#features-used-in-this-example)
- [Example workflow](#example-workflow)
- [Understanding the example](#understanding-the-example)
- [Next steps](#next-steps)
## Example overview
{% data reusables.actions.example-workflow-intro-ci %} When this workflow is triggered, it tests your code using a matrix of test combinations with `npm test`.
{% data reusables.actions.example-diagram-intro %}
![Overview diagram of workflow steps](/assets/images/help/images/overview-actions-using-concurrency-expressions-and-a-test-matrix.png)
## Features used in this example
{% data reusables.actions.example-table-intro %}
| **Feature** | **Implementation** |
| --- | --- |
{% data reusables.actions.workflow-dispatch-table-entry %}
{% data reusables.actions.pull-request-table-entry %}
{% data reusables.actions.cron-table-entry %}
{% data reusables.actions.permissions-table-entry %}
{% data reusables.actions.concurrency-table-entry %}
| Running the job on different runners, depending on the repository: | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
{% data reusables.actions.if-conditions-table-entry %}
| Using a matrix to create different test configurations: | [`matrix`](/actions/using-jobs/using-a-build-matrix-for-your-jobs)|
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
| Caching dependencies: | [`actions/cache`](/actions/advanced-guides/caching-dependencies-to-speed-up-workflows)|
| Running tests on the runner: | `npm test`|
## Example workflow
{% data reusables.actions.example-docs-engineering-intro %} [`test.yml`](https://github.com/github/docs/blob/main/.github/workflows/test.yml).
{% data reusables.actions.note-understanding-example %}
<table style="width:350px">
<thead>
<tr>
<th style="width:100%"></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: Node.js Tests
# **What it does**: Runs our tests.
# **Why we have it**: We want our tests to pass before merging code.
# **Who does it impact**: Docs engineering, open-source engineering contributors.
on:
workflow_dispatch:
pull_request:
push:
branches:
- gh-readonly-queue/main/**
permissions:
contents: read
# Needed for the 'trilom/file-changes-action' action
pull-requests: read
# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
group: {% raw %}'${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'{% endraw %}
cancel-in-progress: true
jobs:
test:
# Run on self-hosted if the private repo or ubuntu-latest if the public repo
# See pull # 17442 in the private repo for context
runs-on: {% raw %}${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}{% endraw %}
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
# The same array lives in test-windows.yml, so make any updates there too.
test-group:
[
content,
graphql,
meta,
rendering,
routing,
unit,
linting,
translations,
]
steps:
# Each of these ifs needs to be repeated at each step to make sure the required check still runs
# Even if if doesn't do anything
- name: Check out repo
uses: {% data reusables.actions.action-checkout %}
with:
# Not all test suites need the LFS files. So instead, we opt to
# NOT clone them initially and instead, include them manually
# only for the test groups that we know need the files.
lfs: {% raw %}${{ matrix.test-group == 'content' }}{% endraw %}
# Enables cloning the Early Access repo later with the relevant PAT
persist-credentials: 'false'
- name: Figure out which docs-early-access branch to checkout, if internal repo
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
id: check-early-access
uses: {% data reusables.actions.action-github-script %}
env:
BRANCH_NAME: {% raw %}${{ github.head_ref || github.ref_name }}{% endraw %}
with:
github-token: {% raw %}${{ secrets.DOCUBOT_REPO_PAT }}{% endraw %}
result-encoding: string
script: |
// If being run from a PR, this becomes 'my-cool-branch'.
// If run on main, with the `workflow_dispatch` action for
// example, the value becomes 'main'.
const { BRANCH_NAME } = process.env
try {
const response = await github.repos.getBranch({
owner: 'github',
repo: 'docs-early-access',
BRANCH_NAME,
})
console.log(`Using docs-early-access branch called '${BRANCH_NAME}'.`)
return BRANCH_NAME
} catch (err) {
if (err.status === 404) {
console.log(`There is no docs-early-access branch called '${BRANCH_NAME}' so checking out 'main' instead.`)
return 'main'
}
throw err
}
- name: Check out docs-early-access too, if internal repo
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
uses: {% data reusables.actions.action-checkout %}
with:
repository: github/docs-early-access
token: {% raw %}${{ secrets.DOCUBOT_REPO_PAT }}{% endraw %}
path: docs-early-access
ref: {% raw %}${{ steps.check-early-access.outputs.result }}{% endraw %}
- name: Merge docs-early-access repo's folders
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
run: |
mv docs-early-access/assets assets/images/early-access
mv docs-early-access/content content/early-access
mv docs-early-access/data data/early-access
rm -r docs-early-access
# This is necessary when LFS files where cloned but does nothing
# if actions/checkout was run with `lfs:false`.
- name: Checkout LFS objects
run: git lfs checkout
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
id: get_diff_files
with:
# So that `steps.get_diff_files.outputs.files` becomes
# a string like `foo.js path/bar.md`
output: ' '
- name: Insight into changed files
run: |
# Must to do this because the list of files can be HUGE. Especially
# in a repo-sync when there are lots of translation files involved.
echo {% raw %}"${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt{% endraw %}
- name: Setup node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.14.x
cache: npm
- name: Install dependencies
run: npm ci
- name: Cache nextjs build
uses: {% data reusables.actions.action-cache %}
with:
path: .next/cache
key: {% raw %}${{ runner.os }}-nextjs-${{ hashFiles('package*.json') }}{% endraw %}
- name: Run build script
run: npm run build
- name: Run tests
env:
DIFF_FILE: get_diff_files.txt
CHANGELOG_CACHE_FILE_PATH: tests/fixtures/changelog-feed.json
run: npm test -- {% raw %}tests/${{ matrix.test-group }}/{% endraw %}
```
</tr>
</td>
</tbody>
</table>
## Understanding the example
 {% data reusables.actions.example-explanation-table-intro %}
<table style="width:350px">
<thead>
<tr>
<th style="width:60%"><b>Code</b></th>
<th style="width:40%"><b>Explanation</b></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: Node.js Tests
```
</td>
<td>
{% data reusables.actions.explanation-name-key %}
</td>
</tr>
<tr>
<td>
```yaml{:copy}
on:
```
</td>
<td>
The `on` keyword lets you define the events that trigger when the workflow is run. You can define multiple events here. For more information, see "[Triggering a workflow](/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
workflow_dispatch:
```
</td>
<td>
Add the `workflow_dispatch` event if you want to be able to manually run this workflow in the UI. For more information, see [`workflow_dispatch`](/actions/reference/events-that-trigger-workflows#workflow_dispatch).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
pull_request:
```
</td>
<td>
Add the `pull_request` event, so that the workflow runs automatically every time a pull request is created or updated. For more information, see [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
push:
branches:
- gh-readonly-queue/main/**
```
</td>
<td>
Add the `push` event, so that the workflow runs automatically every time a commit is pushed to a branch matching the filter `gh-readonly-queue/main/**`. For more information, see [`push`](/actions/using-workflows/events-that-trigger-workflows#push).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
permissions:
contents: read
pull-requests: read
```
</td>
<td>
Modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "[Assigning permissions to jobs](/actions/using-jobs/assigning-permissions-to-jobs)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
concurrency:
group: {% raw %}'${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'{% endraw %}
```
</td>
<td>
Creates a concurrency group for specific events, and uses the `||` operator to define fallback values. For more information, see "[Using concurrency](/actions/using-jobs/using-concurrency)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
cancel-in-progress: true
```
</td>
<td>
Cancels any currently running job or workflow in the same concurrency group.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
jobs:
```
</td>
<td>
Groups together all the jobs that run in the workflow file.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
test:
```
</td>
<td>
Defines a job with the ID `test` that is stored within the `jobs` key.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
runs-on: {% raw %}${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}{% endraw %}
```
</td>
<td>
Configures the job to run on a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner, depending on the repository running the workflow. In this example, the job will run on a self-hosted runner if the repository is named `docs-internal` and is within the `github` organization. If the repository doesn't match this path, then it will run on an `ubuntu-latest` runner hosted by {% data variables.product.prodname_dotcom %}. For more information on these options see "[Choosing the runner for a job](/actions/using-jobs/choosing-the-runner-for-a-job)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
timeout-minutes: 60
```
</td>
<td>
Sets the maximum number of minutes to let the job run before it is automatically canceled. For more information, see [`timeout-minutes`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
strategy:
```
</td>
<td>
This section defines the build matrix for your jobs.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
fail-fast: false
```
</td>
<td>
Setting `fail-fast` to `false` prevents {% data variables.product.prodname_dotcom %} from cancelling all in-progress jobs if any matrix job fails.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
matrix:
test-group:
[
content,
graphql,
meta,
rendering,
routing,
unit,
linting,
translations,
]
```
</td>
<td>
Creates a matrix named `test-group`, with an array of test groups. These values match the names of test groups that will be run by `npm test`.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
steps:
```
</td>
<td>
Groups together all the steps that will run as part of the `test` job. Each job in a workflow has its own `steps` section.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Check out repo
uses: {% data reusables.actions.action-checkout %}
with:
lfs: {% raw %}${{ matrix.test-group == 'content' }}{% endraw %}
persist-credentials: 'false'
```
</td>
<td>
The `uses` keyword tells the job to retrieve the action named `actions/checkout`. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will run against the repository's code or you are using an action defined in the repository. Some extra options are provided to the action using the `with` key.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Figure out which docs-early-access branch to checkout, if internal repo
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
id: check-early-access
uses: {% data reusables.actions.action-github-script %}
env:
BRANCH_NAME: {% raw %}${{ github.head_ref || github.ref_name }}{% endraw %}
with:
github-token: {% raw %}${{ secrets.DOCUBOT_REPO_PAT }}{% endraw %}
result-encoding: string
script: |
// If being run from a PR, this becomes 'my-cool-branch'.
// If run on main, with the `workflow_dispatch` action for
// example, the value becomes 'main'.
const { BRANCH_NAME } = process.env
try {
const response = await github.repos.getBranch({
owner: 'github',
repo: 'docs-early-access',
BRANCH_NAME,
})
console.log(`Using docs-early-access branch called '${BRANCH_NAME}'.`)
return BRANCH_NAME
} catch (err) {
if (err.status === 404) {
console.log(`There is no docs-early-access branch called '${BRANCH_NAME}' so checking out 'main' instead.`)
return 'main'
}
throw err
}
```
</td>
<td>
If the current repository is the `github/docs-internal` repository, this step uses the `actions/github-script` action to run a script to check if there is a branch called `docs-early-access`.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Check out docs-early-access too, if internal repo
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
uses: {% data reusables.actions.action-checkout %}
with:
repository: github/docs-early-access
token: {% raw %}${{ secrets.DOCUBOT_REPO_PAT }}{% endraw %}
path: docs-early-access
ref: {% raw %}${{ steps.check-early-access.outputs.result }}{% endraw %}
```
</td>
<td>
If the current repository is the `github/docs-internal` repository, this step checks out the branch from the `github/docs-early-access` that was identified in the previous step.
</tr>
<tr>
<td>
```yaml{:copy}
- name: Merge docs-early-access repo's folders
if: {% raw %}${{ github.repository == 'github/docs-internal' }}{% endraw %}
run: |
mv docs-early-access/assets assets/images/early-access
mv docs-early-access/content content/early-access
mv docs-early-access/data data/early-access
rm -r docs-early-access
```
</td>
<td>
If the current repository is the `github/docs-internal` repository, this step uses the `run` keyword to execute shell commands to move the `docs-early-access` repository's folders into the main repository's folders.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Checkout LFS objects
run: git lfs checkout
```
</td>
<td>
This step runs a command to check out LFS objects from the repository.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
id: get_diff_files
with:
# So that `steps.get_diff_files.outputs.files` becomes
# a string like `foo.js path/bar.md`
output: ' '
```
</td>
<td>
This step uses the `trilom/file-changes-action` action to gather the files changed in the pull request, so they can be analyzed in the next step. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Insight into changed files
run: |
echo {% raw %}"${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt{% endraw %}
```
</td>
<td>
This step runs a shell command that uses an output from the previous step to create a file containing the list of files changed in the pull request.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Setup node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.14.x
cache: npm
```
</td>
<td>
This step uses the `actions/setup-node` action to install the specified version of the `node` software package on the runner, which gives you access to the `npm` command.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Install dependencies
run: npm ci
```
</td>
<td>
This step runs the `npm ci` shell command to install the npm software packages for the project.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Cache nextjs build
uses: {% data reusables.actions.action-cache %}
with:
path: .next/cache
key: {% raw %}${{ runner.os }}-nextjs-${{ hashFiles('package*.json') }}{% endraw %}
```
</td>
<td>
This step uses the `actions/cache` action to cache the Next.js build, so that the workflow will attempt to retrieve a cache of the build, and not rebuild it from scratch every time. For more information, see "[Caching dependencies to speed up workflows](/actions/using-workflows/caching-dependencies-to-speed-up-workflows)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Run build script
run: npm run build
```
</td>
<td>
This step runs the build script.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Run tests
env:
DIFF_FILE: get_diff_files.txt
CHANGELOG_CACHE_FILE_PATH: tests/fixtures/changelog-feed.json
run: npm test -- {% raw %}tests/${{ matrix.test-group }}/{% endraw %}
```
</td>
<td>
This step runs the tests using `npm test`, and the test matrix provides a different value for {% raw %}`${{ matrix.test-group }}`{% endraw %} for each job in the matrix. It uses the `DIFF_FILE` environment variable to know which files have changed, and uses the `CHANGELOG_CACHE_FILE_PATH` environment variable for the changelog cache file.
</td>
</tr>
</tbody>
</table>
## Next steps
{% data reusables.actions.learning-actions %}

421
content/actions/examples/using-scripts-to-test-your-code-on-a-runner.md Normal file
View File

@@ -0,0 +1,421 @@
---
title: Using scripts to test your code on a runner
shortTitle: Using scripts to test your code on a runner
intro: 'How to use essential {% data variables.product.prodname_actions %} features for continuous integration (CI).'
versions:
fpt: '*'
ghes: '> 3.1'
ghae: '*'
ghec: '*'
showMiniToc: false
type: how_to
topics:
- Workflows
---
{% data reusables.actions.enterprise-github-hosted-runners %}
- [Example overview](#example-overview)
- [Features used in this example](#features-used-in-this-example)
- [Example workflow](#example-workflow)
- [Understanding the example](#understanding-the-example)
- [Next steps](#next-steps)
## Example overview
{% data reusables.actions.example-workflow-intro-ci %} When this workflow is triggered, it automatically runs a script that checks whether the {% data variables.product.prodname_dotcom %} Docs site has any broken links.
{% data reusables.actions.example-diagram-intro %}
![Overview diagram of workflow steps](/assets/images/help/images/overview-actions-using-scripts-ci-example.png)
## Features used in this example
{% data reusables.actions.example-table-intro %}
| **Feature** | **Implementation** |
| --- | --- |
{% data reusables.actions.push-table-entry %}
{% data reusables.actions.pull-request-table-entry %}
{% data reusables.actions.workflow-dispatch-table-entry %}
{% data reusables.actions.permissions-table-entry %}
{% data reusables.actions.concurrency-table-entry %}
| Running the job on different runners, depending on the repository: | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
| Using a third-party action: | [`trilom/file-changes-action`](https://github.com/trilom/file-changes-action)|
| Running a script on the runner: | Using `./script/rendered-content-link-checker.mjs` |
## Example workflow
{% data reusables.actions.example-docs-engineering-intro %} [`link-check-all.yml`](https://github.com/github/docs/blob/main/.github/workflows/link-check-all.yml).
{% data reusables.actions.note-understanding-example %}
<table style="width:350px">
<thead>
<tr>
<th style="width:100%"></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: 'Link Checker: All English'
# **What it does**: Renders the content of every page and check all internal links.
# **Why we have it**: To make sure all links connect correctly.
# **Who does it impact**: Docs content.
on:
workflow_dispatch:
push:
branches:
- main
pull_request:
permissions:
contents: read
# Needed for the 'trilom/file-changes-action' action
pull-requests: read
# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
group: {% raw %}'${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'{% endraw %}
cancel-in-progress: true
jobs:
check-links:
runs-on: {% raw %}${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}{% endraw %}
steps:
- name: Checkout
uses: {% data reusables.actions.action-checkout %}
- name: Setup node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.13.x
cache: npm
- name: Install
run: npm ci
# Creates file "${{ env.HOME }}/files.json", among others
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'
# For verification
- name: Show files changed
run: cat $HOME/files.json
- name: Link check (warnings, changed files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--max 100 \
--check-anchors \
--check-images \
--verbose \
--list $HOME/files.json
- name: Link check (critical, all files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--exit \
--verbose \
--check-images \
--level critical
```
</tr>
</td>
</tbody>
</table>
## Understanding the example
{% data reusables.actions.example-explanation-table-intro %}
<table style="width:350px">
<thead>
<tr>
<th style="width:60%"><b>Code</b></th>
<th style="width:40%"><b>Explanation</b></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: 'Link Checker: All English'
```
</td>
<td>
{% data reusables.actions.explanation-name-key %}
</td>
</tr>
<tr>
<td>
```yaml{:copy}
on:
```
</td>
<td>
The `on` keyword lets you define the events that trigger when the workflow is run. You can define multiple events here. For more information, see "[Triggering a workflow](/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
workflow_dispatch:
```
</td>
<td>
Add the `workflow_dispatch` event if you want to be able to manually run this workflow from the UI. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
push:
branches:
- main
```
</td>
<td>
Add the `push` event, so that the workflow runs automatically every time a commit is pushed to a branch called `main`. For more information, see [`push`](/actions/using-workflows/events-that-trigger-workflows#push).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
pull_request:
```
</td>
<td>
Add the `pull_request` event, so that the workflow runs automatically every time a pull request is created or updated. For more information, see [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
permissions:
contents: read
pull-requests: read
```
</td>
<td>
Modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "[Assigning permissions to jobs](/actions/using-jobs/assigning-permissions-to-jobs)."
</td>
</tr>
<tr>
<td>
{% raw %}
```yaml{:copy}
concurrency:
group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
```
{% endraw %}
</td>
<td>
Creates a concurrency group for specific events, and uses the `||` operator to define fallback values. For more information, see "[Using concurrency](/actions/using-jobs/using-concurrency)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
cancel-in-progress: true
```
</td>
<td>
Cancels any currently running job or workflow in the same concurrency group.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
jobs:
```
</td>
<td>
Groups together all the jobs that run in the workflow file.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
check-links:
```
</td>
<td>
Defines a job with the ID `check-links` that is stored within the `jobs` key.
</td>
</tr>
<tr>
<td>
{% raw %}
```yaml{:copy}
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
```
{% endraw %}
</td>
<td>
Configures the job to run on a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner, depending on the repository running the workflow. In this example, the job will run on a self-hosted runner if the repository is named `docs-internal` and is within the `github` organization. If the repository doesn't match this path, then it will run on an `ubuntu-latest` runner hosted by {% data variables.product.prodname_dotcom %}. For more information on these options see "[Choosing the runner for a job](/actions/using-jobs/choosing-the-runner-for-a-job)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
steps:
```
</td>
<td>
Groups together all the steps that will run as part of the `check-links` job. Each job in a workflow has its own `steps` section.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Checkout
uses: {% data reusables.actions.action-checkout %}
```
</td>
<td>
The `uses` keyword tells the job to retrieve the action named `actions/checkout`. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will run against the repository's code or you are using an action defined in the repository.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Setup node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.13.x
cache: npm
```
</td>
<td>
This step uses the `actions/setup-node` action to install the specified version of the Node.js software package on the runner, which gives you access to the `npm` command.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Install
run: npm ci
```
</td>
<td>
The `run` keyword tells the job to execute a command on the runner. In this case, `npm ci` is used to install the npm software packages for the project.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'
```
</td>
<td>
Uses the `trilom/file-changes-action` action to gather all the changed files. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Show files changed
run: cat $HOME/files.json
```
</td>
<td>
Lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Link check (warnings, changed files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--max 100 \
--check-anchors \
--check-images \
--verbose \
--list $HOME/files.json
```
</td>
<td>
This step uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes all the parameters it needs to run.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Link check (critical, all files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--exit \
--verbose \
--check-images \
--level critical
```
</td>
<td>
This step also uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes a different set of parameters.
</tr>
</tbody>
</table>
## Next steps
{% data reusables.actions.learning-actions %}

490
content/actions/examples/using-the-github-cli-on-a-runner.md Normal file
View File

@@ -0,0 +1,490 @@
---
title: Using the GitHub CLI on a runner
shortTitle: Using the GitHub CLI on a runner
intro: 'How to use advanced {% data variables.product.prodname_actions %} features for continuous integration (CI).'
versions:
fpt: '*'
ghes: '> 3.1'
ghae: '*'
ghec: '*'
showMiniToc: false
type: how_to
topics:
- Workflows
---
{% data reusables.actions.enterprise-github-hosted-runners %}
- [Example overview](#example-overview)
- [Features used in this example](#features-used-in-this-example)
- [Example workflow](#example-workflow)
- [Understanding the example](#understanding-the-example)
- [Next steps](#next-steps)
## Example overview
{% data reusables.actions.example-workflow-intro-ci %} When this workflow is triggered, it automatically runs a script that checks whether the {% data variables.product.prodname_dotcom %} Docs site has any broken links. If any broken links are found, the workflow uses the {% data variables.product.prodname_dotcom %} CLI to create a {% data variables.product.prodname_dotcom %} issue with the details.
{% data reusables.actions.example-diagram-intro %}
![Overview diagram of workflow steps](/assets/images/help/images/overview-actions-using-cli-ci-example.png)
## Features used in this example
{% data reusables.actions.example-table-intro %}
| **Feature** | **Implementation** |
| --- | --- |
{% data reusables.actions.cron-table-entry %}
{% data reusables.actions.permissions-table-entry %}
{% data reusables.actions.if-conditions-table-entry %}
{% data reusables.actions.secrets-table-entry %}
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
| Using a third-party action: | [`peter-evans/create-issue-from-file`](https://github.com/peter-evans/create-issue-from-file)|
| Running shell commands on the runner: | [`run`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun) |
| Running a script on the runner: | Using `script/check-english-links.js` |
| Generating an output file: | Piping the output using the `>` operator |
| Checking for existing issues using {% data variables.product.prodname_cli %}: | [`gh issue list`](https://cli.github.com/manual/gh_issue_list) |
| Commenting on an issue using {% data variables.product.prodname_cli %}: | [`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) |
## Example workflow
{% data reusables.actions.example-docs-engineering-intro %} [`check-all-english-links.yml`](https://github.com/github/docs/blob/main/.github/workflows/check-all-english-links.yml).
{% data reusables.actions.note-understanding-example %}
<table style="width:350px">
<thead>
<tr>
<th style="width:70%"></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: Check all English links
# **What it does**: This script once a day checks all English links and reports in issues.
# **Why we have it**: We want to know if any links break.
# **Who does it impact**: Docs content.
on:
workflow_dispatch:
schedule:
- cron: '40 19 * * *' # once a day at 19:40 UTC / 11:40 PST
permissions:
contents: read
issues: write
jobs:
check_all_english_links:
name: Check all links
if: github.repository == 'github/docs-internal'
runs-on: ubuntu-latest
env:
GITHUB_TOKEN: {% raw %}${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}{% endraw %}
FIRST_RESPONDER_PROJECT: Docs content first responder
REPORT_AUTHOR: docubot
REPORT_LABEL: broken link report
REPORT_REPOSITORY: github/docs-content
steps:
- name: Check out repo's default branch
uses: {% data reusables.actions.action-checkout %}
- name: Setup Node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.13.x
cache: npm
- name: npm ci
run: npm ci
- name: npm run build
run: npm run build
- name: Run script
run: |
script/check-english-links.js > broken_links.md
# check-english-links.js returns 0 if no links are broken, and 1 if any links
# are broken. When an Actions step's exit code is 1, the action run's job status
# is failure and the run ends. The following steps create an issue for the
# broken link report only if any links are broken, so {% raw %}`if: ${{ failure() }}`{% endraw %}
# ensures the steps run despite the previous step's failure of the job.
- if: {% raw %}${{ failure() }}{% endraw %}
name: Get title for issue
id: check
run: echo "::set-output name=title::$(head -1 broken_links.md)"
- if: {% raw %}${{ failure() }}{% endraw %}
name: Create issue from file
id: broken-link-report
uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
with:
token: {% raw %}${{ env.GITHUB_TOKEN }}{% endraw %}
title: {% raw %}${{ steps.check.outputs.title }}{% endraw %}
content-filepath: ./broken_links.md
repository: {% raw %}${{ env.REPORT_REPOSITORY }}{% endraw %}
labels: {% raw %}${{ env.REPORT_LABEL }}{% endraw %}
- if: {% raw %}${{ failure() }}{% endraw %}
name: Close and/or comment on old issues
env:
{% raw %}NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}'{% endraw %}
run: |
gh alias set list-reports "issue list \
--repo {% raw %}${{ env.REPORT_REPOSITORY }} \{% endraw %}
--author {% raw %}${{ env.REPORT_AUTHOR }} \{% endraw %}
--label {% raw %}'${{ env.REPORT_LABEL }}'"{% endraw %}
# Link to the previous report from the new report that triggered this
# workflow run.
previous_report_url=$(gh list-reports \
--state all \
--limit 2 \
--json url \
--jq '.[].url' \
| grep -v {% raw %}${{ env.NEW_REPORT_URL }}{% endraw %} | head -1)
gh issue comment {% raw %}${{ env.NEW_REPORT_URL }}{% endraw %} --body "⬅️ [Previous report]($previous_report_url)"
# If an old report is open and assigned to someone, link to the newer
# report without closing the old report.
for issue_url in $(gh list-reports \
--json assignees,url \
--jq '.[] | select (.assignees != []) | .url'); do
if [ "$issue_url" != {% raw %}"${{ env.NEW_REPORT_URL }}"{% endraw %} ]; then
gh issue comment $issue_url --body "➡️ [Newer report]({% raw %}${{ env.NEW_REPORT_URL }}{% endraw %})"
fi
done
# Link to the newer report from any older report that is still open,
# then close the older report and remove it from the first responder's
# project board.
for issue_url in $(gh list-reports \
--search 'no:assignee' \
--json url \
--jq '.[].url'); do
if [ "$issue_url" != {% raw %}"${{ env.NEW_REPORT_URL }}"{% endraw %} ]; then
gh issue comment $issue_url --body "➡️ [Newer report]({% raw %}${{ env.NEW_REPORT_URL }})"{% endraw %}
gh issue close $issue_url
gh issue edit $issue_url --remove-project "{% raw %}${{ env.FIRST_RESPONDER_PROJECT }}"{% endraw %}
fi
done
```
</tr>
</td>
</tbody>
</table>
## Understanding the example
{% data reusables.actions.example-explanation-table-intro %}
<table style="width:350px">
<thead>
<tr>
<th style="width:60%"><b>Code</b></th>
<th style="width:40%"><b>Explanation</b></th>
</tr>
</thead>
<tbody>
<tr>
<td>
```yaml{:copy}
name: Check all English links
```
</td>
<td>
{% data reusables.actions.explanation-name-key %}
</td>
</tr>
<tr>
<td>
```yaml{:copy}
on:
workflow_dispatch:
schedule:
- cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST
```
</td>
<td>
Defines the `workflow_dispatch` and `scheduled` as triggers for the workflow:
* The `workflow_dispatch` lets you manually run this workflow from the UI. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
* The `schedule` event lets you use `cron` syntax to define a regular interval for automatically triggering the workflow. For more information, see [`schedule`](/actions/reference/events-that-trigger-workflows#schedule).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
permissions:
contents: read
issues: write
```
</td>
<td>
Modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "[Assigning permissions to jobs](/actions/using-jobs/assigning-permissions-to-jobs)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
jobs:
```
</td>
<td>
Groups together all the jobs that run in the workflow file.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
check_all_english_links:
name: Check all links
```
</td>
<td>
Defines a job with the ID `check_all_english_links`, and the name `Check all links`, that is stored within the `jobs` key.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
if: github.repository == 'github/docs-internal'
```
</td>
<td>
Only run the `check_all_english_links` job if the repository is named `docs-internal` and is within the `github` organization. Otherwise, the job is marked as _skipped_.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
runs-on: ubuntu-latest
```
</td>
<td>
Configures the job to run on an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by {% data variables.product.prodname_dotcom %}. For syntax examples using other runners, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)."
</td>
</tr>
<tr>
<td>
```yaml{:copy}
env:
GITHUB_TOKEN: {% raw %}${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}{% endraw %}
REPORT_AUTHOR: docubot
REPORT_LABEL: broken link report
REPORT_REPOSITORY: github/docs-content
```
</td>
<td>
Creates custom environment variables, and redefines the built-in `GITHUB_TOKEN` variable to use a custom [secret](/actions/security-guides/encrypted-secrets). These variables will be referenced later in the workflow.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
steps:
```
</td>
<td>
Groups together all the steps that will run as part of the `check_all_english_links` job. Each job in the workflow has its own `steps` section.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Check out repo's default branch
uses: {% data reusables.actions.action-checkout %}
```
</td>
<td>
The `uses` keyword tells the job to retrieve the action named `actions/checkout`. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will run against the repository's code or you are using an action defined in the repository.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Setup Node
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: 16.8.x
cache: npm
```
</td>
<td>
This step uses the `actions/setup-node` action to install the specified version of the `node` software package on the runner, which gives you access to the `npm` command.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Run the "npm ci" command
run: npm ci
- name: Run the "npm run build" command
run: npm run build
```
</td>
<td>
The `run` keyword tells the job to execute a command on the runner. In this case, the `npm ci` and `npm run build` commands are run as separate steps to install and build the Node.js application in the repository.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- name: Run script
run: |
script/check-english-links.js > broken_links.md
```
</td>
<td>
This `run` command executes a script that is stored in the repository at `script/check-english-links.js`, and pipes the output to a file called `broken_links.md`.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- if: {% raw %}${{ failure() }}{% endraw %}
name: Get title for issue
id: check
run: echo "::set-output name=title::$(head -1 broken_links.md)"
```
</td>
<td>
If the `check-english-links.js` script detects broken links and returns a non-zero (failure) exit status, then use a [workflow command](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter) to set an output that has the value of the first line of the `broken_links.md` file (this is used the next step).
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- if: {% raw %}${{ failure() }}{% endraw %}
name: Create issue from file
id: broken-link-report
uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
with:
token: {% raw %}${{ env.GITHUB_TOKEN }}{% endraw %}
title: {% raw %}${{ steps.check.outputs.title }}{% endraw %}
content-filepath: ./broken_links.md
repository: {% raw %}${{ env.REPORT_REPOSITORY }}{% endraw %}
labels: {% raw %}${{ env.REPORT_LABEL }}{% endraw %}
```
</td>
<td>
Uses the `peter-evans/create-issue-from-file` action to create a new {% data variables.product.prodname_dotcom %} issue. This example is pinned to a specific version of the action, using the `b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e` SHA.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
- if: {% raw %}${{ failure() }}{% endraw %}
name: Close and/or comment on old issues
env:
NEW_REPORT_URL: 'https://github.com/{% raw %}${{ env.REPORT_REPOSITORY }}{% endraw %}/issues/{% raw %}${{ steps.broken-link-report.outputs.issue-number }}{% endraw %}'
run: |
gh alias set list-reports "issue list \
--repo {% raw %}${{ env.REPORT_REPOSITORY }}{% endraw %} \
--author {% raw %}${{ env.REPORT_AUTHOR }}{% endraw %} \
--label '{% raw %}${{ env.REPORT_LABEL }}{% endraw %}'"
previous_report_url=$(gh list-reports \
--state all \
--limit 2 \
--json url \
--jq '.[].url' \
| grep -v {% raw %}${{ env.NEW_REPORT_URL }}{% endraw %} | head -1)
gh issue comment {% raw %}${{ env.NEW_REPORT_URL }}{% endraw %} --body "⬅️ [Previous report]($previous_report_url)"
```
</td>
<td>
Uses [`gh issue list`](https://cli.github.com/manual/gh_issue_list) to locate the previously created issue from earlier runs. This is [aliased](https://cli.github.com/manual/gh_alias_set) to `gh list-reports` for simpler processing in later steps. To get the issue URL, the `jq` expression processes the resulting JSON output.
[`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) is then used to add a comment to the new issue that links to the previous one.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
for issue_url in $(gh list-reports \
--json assignees,url \
--jq '.[] | select (.assignees != []) | .url'); do
if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
fi
done
```
</td>
<td>
If an issue from a previous run is open and assigned to someone, then use [`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) to add a comment with a link to the new issue.
</td>
</tr>
<tr>
<td>
```yaml{:copy}
for issue_url in $(gh list-reports \
--search 'no:assignee' \
--json url \
--jq '.[].url'); do
if [ "$issue_url" != "{% raw %}${{ env.NEW_REPORT_URL }}{% endraw %}" ]; then
gh issue comment $issue_url --body "➡️ [Newer report]({% raw %}${{ env.NEW_REPORT_URL }}{% endraw %})"
gh issue close $issue_url
gh issue edit $issue_url --remove-project "{% raw %}${{ env.FIRST_RESPONDER_PROJECT }}{% endraw %}"
fi
done
```
</td>
<td>
If an issue from a previous run is open and is not assigned to anyone, then:
* Use [`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) to add a comment with a link to the new issue.
* Use [`gh issue close`](https://cli.github.com/manual/gh_issue_close) to close the old issue.
* Use [`gh issue edit`](https://cli.github.com/manual/gh_issue_edit) to edit the old issue to remove it from a specific {% data variables.product.prodname_dotcom %} project board.
</td>
</tr>
</tbody>
</table>
## Next steps
{% data reusables.actions.learning-actions %}