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 tests your code using a matrix of test combinations with npm test
.
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 |
---|---|
Manually running a workflow from the UI | workflow_dispatch |
Triggering a workflow to run automatically | pull_request |
Running a workflow at regular intervals | schedule |
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 |
Preventing a job from running unless specific conditions are met | if |
Using a matrix to create different test configurations | matrix |
Cloning your repository to the runner | actions/checkout |
Installing node on the runner | actions/setup-node |
Caching dependencies | actions/cache |
Running tests on the runner | npm test |
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 test.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. |
|
The |
|
Add the |
|
Add the |
|
Add the |
|
Modifies the default permissions granted to |
|
Creates a concurrency group for specific events, and uses the |
|
Cancels any currently running job or workflow in the same concurrency group. |
|
Groups together all the jobs that run in the workflow file. |
|
Defines a job with the ID |
|
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 |
|
Sets the maximum number of minutes to let the job run before it is automatically canceled. For more information, see |
|
This section defines the build matrix for your jobs. |
|
Setting |
|
Creates a matrix named |
|
Groups together all the steps that will run as part of the |
|
The |
|
If the current repository is the |
|
If the current repository is the |
|
If the current repository is the |
|
This step runs a command to check out LFS objects from the repository. |
|
This step uses the |
|
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. |
|
This step uses the |
|
This step runs the |
|
This step uses the |
|
This step runs the build script. |
|
This step runs the tests using |
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."