Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
Example overview
This article uses an example workflow to demonstrate some of the main CI features of GitHub Actions. When this workflow is triggered, it automatically runs a script that checks whether the GitHub Docs site has any broken links.
The following diagram shows a high level view of the workflow's steps and how they run within the job:
Features used in this example
The example workflow demonstrates the following capabilities of GitHub Actions.
Feature | Implementation |
---|---|
Triggering a workflow to run automatically | push |
Triggering a workflow to run automatically | pull_request |
Manually running a workflow from the UI | workflow_dispatch |
Setting permissions for the token | permissions |
Controlling how many workflow runs or jobs can run at the same time | concurrency |
Running the job on different runners, depending on the repository | runs-on |
Cloning your repository to the runner | actions/checkout |
Installing node on the runner | actions/setup-node |
Using a third-party action | trilom/file-changes-action |
Running a script on the runner | Using ./script/rendered-content-link-checker.mjs |
Example workflow
The following workflow was created by the GitHub Docs Engineering team. To review the latest version of this file in the github/docs
repository, see check-broken-links-github-github.yml
.
Note: Each line of this workflow is explained in the next section at "Understanding the example."
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: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}' cancel-in-progress: true jobs: check-links: runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }} steps: - name: Checkout uses: actions/checkout@v3 - name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm - name: Install run: npm ci # Creates file "$/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
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: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
cancel-in-progress: true
jobs:
check-links:
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup node
uses: actions/setup-node@v3
with:
node-version: 16.13.x
cache: npm
- name: Install
run: npm ci
# Creates file "$/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
Understanding the example
The following table explains how each of these features are used when creating a GitHub Actions workflow.
Code | Explanation |
---|---|
name: 'Link Checker: All English'
|
The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. |
on:
|
The |
workflow_dispatch:
|
Add the |
push: branches: - main
|
Add the |
pull_request:
|
Add the |
permissions: contents: read pull-requests: read
|
Modifies the default permissions granted to |
concurrency: group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
|
Creates a concurrency group for specific events, and uses the |
cancel-in-progress: true
|
Cancels any currently running job or workflow in the same concurrency group. |
jobs:
|
Groups together all the jobs that run in the workflow file. |
check-links:
|
Defines a job with the ID |
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
|
Configures the job to run on a GitHub-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 |
steps:
|
Groups together all the steps that will run as part of the |
- name: Checkout uses: actions/checkout@v3
|
The |
- name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm
|
This step uses the |
- name: Install run: npm ci
|
The |
- name: Gather files changed uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b with: fileOutput: 'json'
|
Uses the |
- name: Show files changed run: cat $HOME/files.json
|
Lists the contents of |
- 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 |
- 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 |
Next steps
- To learn about GitHub Actions concepts, see "Understanding GitHub Actions."
- For more step-by-step guide for creating a basic workflow, see "Quickstart for GitHub Actions."
- If you're comfortable with the basics of GitHub Actions, you can learn about workflows and their features at "About workflows."