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. If any broken links are found, the workflow uses the GitHub CLI to create a GitHub issue with the details.
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 |
---|---|
Running a workflow at regular intervals: | schedule |
Setting permissions for the token: | permissions |
Preventing a job from running unless specific conditions are met: | if |
Referencing secrets in a workflow: | Secrets |
Cloning your repository to the runner: | actions/checkout |
Installing node on the runner: | actions/setup-node |
Using a third-party action: | peter-evans/create-issue-from-file |
Running shell commands on the runner: | run |
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 GitHub CLI: | gh issue list |
Commenting on an issue using GitHub CLI: | gh issue comment |
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-all-english-links.yml
.
Note: Each line of this workflow is explained in the next section at "Understanding the example."
|
Understanding the example
The following table explains how each of these features are used when creating a GitHub Actions workflow.
Code | Explanation |
---|---|
|
The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. |
|
Defines the
|
|
Modifies the default permissions granted to |
|
Groups together all the jobs that run in the workflow file. |
|
Defines a job with the ID |
|
Only run the |
|
Configures the job to run on an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "Workflow syntax for GitHub Actions." |
|
Creates custom environment variables, and redefines the built-in |
|
Groups together all the steps that will run as part of the |
|
The |
|
This step uses the |
|
The |
|
This |
|
If the |
|
Uses the |
|
Uses
|
|
If an issue from a previous run is open and assigned to someone, then use |
|
If an issue from a previous run is open and is not assigned to anyone, then:
|
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."