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