About workflows
Workflow basics
-
One or more events that will trigger the workflow. -
One or more jobs , each of which will execute on a runner machine and run a series of one or more steps . -
Each step can either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.
Triggering a workflow
-
Events that occur in your workflow's repository -
Events that occur outside of GitHub and trigger a repository_dispatch event on GitHub -
Scheduled times -
Manual
Workflow syntax
Create an example workflow
-
In your repository, create the .github/workflows/ directory to store your workflow files. -
In the .github/workflows/ directory, create a new file called learn-github-actions.yml and add the following code. YAML name: learn-github-actions run-name: ${{ github.actor }} is learning GitHub Actions on: [push] jobs: check-bats-version: runs-on: ubuntu-latest steps: - uses: actions/ checkout@v4 - uses: actions/ setup-node@v4 with: node-version: '20' - run: npm install -g bats - run: bats -v name: learn-github-actions run-name: ${{ github.actor }} is learning GitHub Actions on: [ push ] jobs: check-bats-version: runs-on: ubuntu-latest steps: - uses: actions/ checkout@v4 - uses: actions/ setup-node@v4 with: node-version: '20' - run: npm install -g bats - run: bats -v -
Commit these changes and push them to your GitHub repository.
Understanding the workflow file
# Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. If this field is omitted, the name of the workflow file will be used instead. name: learn-github-actions # Optional - The name for workflow runs generated from the workflow, which will appear in the list of workflow runs on your repository's "Actions" tab. This example uses an expression with the `github` context to display the username of the actor that triggered the workflow run. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#run-name). " run-name: ${{ github.actor }} is learning GitHub Actions # Specifies the trigger for this workflow. This example uses the `push` event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "[AUTOTITLE] (/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). " on: [push] # Groups together all the jobs that run in the `learn-github-actions` workflow. jobs: # Defines a job named `check-bats-version`. The child keys will define properties of the job. check-bats-version: # Configures the job to run on the latest version of 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 "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)" runs-on: ubuntu-latest # Groups together all the steps that run in the `check-bats-version` job. Each item nested under this section is a separate action or shell script. steps: # The `uses` keyword specifies that this step will run `v4` of the `actions/checkout` action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will use the repository's code. - uses: actions/ checkout@v4 # This step uses the `actions/ setup-node@v4 ` action to install the specified version of the Node.js. (This example uses version 20.) This puts both the `node` and `npm` commands in your `PATH`. - uses: actions/ setup-node@v4 with: node-version: '20' # The `run` keyword tells the job to execute a command on the runner. In this case, you are using `npm` to install the `bats` software testing package. - run: npm install -g bats # Finally, you'll run the `bats` command with a parameter that outputs the software version. - run: bats -v
name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [ push ]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: actions/ checkout@v4
- uses: actions/ setup-node@v4
with:
node-version: '20'
- run: npm install -g bats
- run: bats -v
# Optional - The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. If this field is omitted, the name of the workflow file will be used instead.
name: learn-github-actions
# Optional - The name for workflow runs generated from the workflow, which will appear in the list of workflow runs on your repository's "Actions" tab. This example uses an expression with the `github` context to display the username of the actor that triggered the workflow run. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#run-name). "
run-name: ${{ github.actor }} is learning GitHub Actions
# Specifies the trigger for this workflow. This example uses the `push` event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "[AUTOTITLE] (/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). "
on: [ push ] # Groups together all the jobs that run in the `learn-github-actions` workflow.
jobs:
# Defines a job named `check-bats-version`. The child keys will define properties of the job.
check-bats-version:
# Configures the job to run on the latest version of 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 "[AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)"
runs-on: ubuntu-latest
# Groups together all the steps that run in the `check-bats-version` job. Each item nested under this section is a separate action or shell script.
steps:
# The `uses` keyword specifies that this step will run `v4` of the `actions/checkout` action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will use the repository's code.
- uses: actions/ checkout@v4
# This step uses the `actions/ setup-node@v4 ` action to install the specified version of the Node.js. (This example uses version 20.) This puts both the `node` and `npm` commands in your `PATH`.
- uses: actions/ setup-node@v4
with:
node-version: '20'
# The `run` keyword tells the job to execute a command on the runner. In this case, you are using `npm` to install the `bats` software testing package.
- run: npm install -g bats
# Finally, you'll run the `bats` command with a parameter that outputs the software version.
- run: bats -v
Visualizing the workflow file
Viewing the activity for a workflow run
-
On GitHub.com, navigate to the main page of the repository. -
Under your repository name, click Actions . -
In the left sidebar, click the workflow you want to see. -
From the list of workflow runs, click the name of the run to see the workflow run summary. -
In the left sidebar or in the visualization graph, click the job you want to see. -
To view the results of a step, click the step.
Using starter workflows
Advanced workflow features
Storing secrets
jobs:
example-job:
runs-on: ubuntu-latest
steps:
- name: Retrieve secret
env:
super_secret: ${{ secrets.SUPERSECRET }}
run: | example-command "$super_secret"
Creating dependent jobs
jobs:
setup:
runs-on: ubuntu-latest
steps:
- run: ./setup_server.sh
build:
needs: setup
runs-on: ubuntu-latest
steps:
- run: ./build_server.sh
test:
needs: build
runs-on: ubuntu-latest
steps:
- run: ./test_server.sh
Using a matrix
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node: [ fourteen , sixteen ] steps:
- uses: actions/ setup-node@v4
with:
node-version: ${{ matrix.node }}
Caching dependencies
jobs:
example-job:
steps:
- name: Cache node modules
uses: actions/ cache@v3
env:
cache-name: cache-node-modules
with:
path: ~/.npm
key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: | ${{ runner.os }}-build-${{ env.cache-name }}-
Using databases and service containers
jobs:
container-job:
runs-on: ubuntu-latest
container: node:10.18-jessie
services:
postgres:
image: postgres
steps:
- name: Check out repository code
uses: actions/ checkout@v4
- name: Install dependencies
run: npm ci
- name: Connect to PostgreSQL
run: node client.js
env:
POSTGRES_HOST: postgres
POSTGRES_PORT: five thousand four hundred and thirty-two
Using labels to route workflows
jobs:
example-job:
runs-on: [ self-hosted , linux , x64 , gpu ]
Reusing workflows
Security hardening for workflows
Using environments