| + |
|---|
| + +```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 %} +``` + |
| Code | +Explanation | +
|---|---|
| + +```yaml{:copy} +name: Node.js Tests +``` + | ++ +{% data reusables.actions.explanation-name-key %} + | +
| + +```yaml{:copy} +on: +``` + | ++ +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)." + | +
| + +```yaml{:copy} + workflow_dispatch: +``` + | ++ +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). + | +
| + +```yaml{:copy} + pull_request: +``` + | ++ +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). + | +
| + +```yaml{:copy} + push: + branches: + - gh-readonly-queue/main/** +``` + | ++ +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). + | +
| + +```yaml{:copy} +permissions: + contents: read + pull-requests: read +``` + | ++ +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)." + | +
| + + +```yaml{:copy} +concurrency: + group: {% raw %}'${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'{% endraw %} +``` + | ++ +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)." + | +
| + +```yaml{:copy} + cancel-in-progress: true +``` + | ++ +Cancels any currently running job or workflow in the same concurrency group. + | +
| + +```yaml{:copy} +jobs: +``` + | ++ +Groups together all the jobs that run in the workflow file. + | +
| + +```yaml{:copy} + test: +``` + | ++ +Defines a job with the ID `test` that is stored within the `jobs` key. + | +
| + +```yaml{:copy} + runs-on: {% raw %}${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}{% endraw %} +``` + | ++ +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)." + | +
| + +```yaml{:copy} + timeout-minutes: 60 +``` + | ++ +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). + | +
| + +```yaml{:copy} + strategy: +``` + | ++ This section defines the build matrix for your jobs. + | +
| + +```yaml{:copy} + fail-fast: false +``` + | ++ +Setting `fail-fast` to `false` prevents {% data variables.product.prodname_dotcom %} from cancelling all in-progress jobs if any matrix job fails. + | +
| + +```yaml{:copy} + matrix: + test-group: + [ + content, + graphql, + meta, + rendering, + routing, + unit, + linting, + translations, + ] +``` + | ++ +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`. + | +
| + +```yaml{:copy} + steps: +``` + | ++ +Groups together all the steps that will run as part of the `test` job. Each job in a workflow has its own `steps` section. + | +
| + +```yaml{:copy} + - name: Check out repo + uses: {% data reusables.actions.action-checkout %} + with: + lfs: {% raw %}${{ matrix.test-group == 'content' }}{% endraw %} + persist-credentials: 'false' +``` + | ++ +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. + | +
| + +```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 + } +``` + | ++ +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`. + | +
| + +```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 %} +``` + | ++ +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. + |
| + +```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 +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Checkout LFS objects + run: git lfs checkout +``` + | ++ +This step runs a command to check out LFS objects from the repository. + | +
| + + +```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: ' ' +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Insight into changed files + run: | + echo {% raw %}"${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt{% endraw %} +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Setup node + uses: {% data reusables.actions.action-setup-node %} + with: + node-version: 16.14.x + cache: npm +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Install dependencies + run: npm ci +``` + | ++ +This step runs the `npm ci` shell command to install the npm software packages for the project. + | +
| + +```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 %} +``` + | ++ +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)." + | +
| + +```yaml{:copy} + - name: Run build script + run: npm run build +``` + | ++ +This step runs the build script. + | +
| + +```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 %} +``` + | ++ +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. + | +
| + |
|---|
| + +```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 +``` + |
| Code | +Explanation | +
|---|---|
| + +```yaml{:copy} +name: 'Link Checker: All English' +``` + | ++ +{% data reusables.actions.explanation-name-key %} + | +
| + +```yaml{:copy} +on: +``` + | ++ +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)." + | +
| + +```yaml{:copy} + workflow_dispatch: +``` + | ++ +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). + | +
| + +```yaml{:copy} + push: + branches: + - main +``` + | ++ +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). + | +
| + +```yaml{:copy} + pull_request: +``` + | ++ +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). + | +
| + +```yaml{:copy} +permissions: + contents: read + pull-requests: read +``` + | ++ +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)." + | +
| + +{% raw %} +```yaml{:copy} +concurrency: + group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}' +``` +{% endraw %} + | ++ +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)." + | +
| + +```yaml{:copy} + cancel-in-progress: true +``` + | ++ +Cancels any currently running job or workflow in the same concurrency group. + | +
| + +```yaml{:copy} +jobs: +``` + | ++ +Groups together all the jobs that run in the workflow file. + | +
| + +```yaml{:copy} + check-links: +``` + | ++ +Defines a job with the ID `check-links` that is stored within the `jobs` key. + | +
| + +{% raw %} +```yaml{:copy} + runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }} +``` +{% endraw %} + | ++ +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)." + | +
| + +```yaml{:copy} + steps: +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Checkout + uses: {% data reusables.actions.action-checkout %} +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Setup node + uses: {% data reusables.actions.action-setup-node %} + with: + node-version: 16.13.x + cache: npm +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Install + run: npm ci +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Gather files changed + uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b + with: + fileOutput: 'json' +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Show files changed + run: cat $HOME/files.json +``` + | ++ +Lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging. + | +
| + +```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 +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Link check (critical, all files) + run: | + ./script/rendered-content-link-checker.mjs \ + --language en \ + --exit \ + --verbose \ + --check-images \ + --level critical +``` + | ++ +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. + |
| + |
|---|
| + +```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 +``` + |
| Code | +Explanation | +
|---|---|
| + +```yaml{:copy} +name: Check all English links +``` + | ++ +{% data reusables.actions.explanation-name-key %} + | +
| + +```yaml{:copy} +on: + workflow_dispatch: + schedule: + - cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST +``` + | ++ +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). + | +
| + +```yaml{:copy} +permissions: + contents: read + issues: write +``` + | ++ +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)." + | +
| + +```yaml{:copy} +jobs: +``` + | ++ +Groups together all the jobs that run in the workflow file. + | +
| + +```yaml{:copy} + check_all_english_links: + name: Check all links +``` + | ++ +Defines a job with the ID `check_all_english_links`, and the name `Check all links`, that is stored within the `jobs` key. + | +
| + +```yaml{:copy} +if: github.repository == 'github/docs-internal' +``` + | ++ +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_. + | +
| + +```yaml{:copy} +runs-on: ubuntu-latest +``` + | ++ +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)." + | +
| + +```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 +``` + | ++ +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. + | +
| + +```yaml{:copy} + steps: +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Check out repo's default branch + uses: {% data reusables.actions.action-checkout %} +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Setup Node + uses: {% data reusables.actions.action-setup-node %} + with: + node-version: 16.8.x + cache: npm +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Run the "npm ci" command + run: npm ci + - name: Run the "npm run build" command + run: npm run build +``` + | ++ +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. + | +
| + +```yaml{:copy} + - name: Run script + run: | + script/check-english-links.js > broken_links.md +``` + | ++ +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`. + | +
| + +```yaml{:copy} + - if: {% raw %}${{ failure() }}{% endraw %} + name: Get title for issue + id: check + run: echo "::set-output name=title::$(head -1 broken_links.md)" +``` + | ++ +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). + | +
| + +```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 %} +``` + | ++ +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. + | +
| + +```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)" +``` + | ++ +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. + | +
| + +```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 +``` + | ++ +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. + | +
| + +```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 +``` + | ++ +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. + | +