Summary
GitHub Actions uses YAML syntax to define the events, jobs, and steps. These YAML files are stored in your code repository, in a directory called .github/workflows
.
- GitHub events (e.g. push, pull request) occur, at a scheduled time, manually, or when events outside of GitHub occur.
- The
.github/workflows
directory in your repository is searched for workflow files at the associated commit SHA or Git ref. The workflow files must be present in that commit SHA or Git ref to be considered.- You can configure workflows to run for one or more events using the
on
workflow syntax.- A new workflow run is triggered for any workflows that have
on:
values that match the triggering event. - When a workflow runs, GitHub sets the
GITHUB_SHA
(commit SHA) andGITHUB_REF
(Git ref) environment variables in the runner environment.
- A new workflow run is triggered for any workflows that have
- You can configure workflows to run for one or more events using the

Github Actions components
- Runner – virtual host machine running Linux, Windows, or macOS
- Event – Specific activity on GitHub that will trigger a workflow listening on the specific event.
- Workflow – What need to be run on the runners on which event that is defined in YAML file inside
.github/workflows/
of a Github repository.- Jobs – Jobs run on a specific runner or Operation System. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the
jobs.<job_id>.needs
keyword.- Steps – A step is an individual task that can run commands in a job. A step can be either an action (defined with
uses:
) or a shell command (defined withrun:
).- Actions – Actions are the smallest portable building block of a workflow. You can create your own actions, or use actions created by the GitHub community.
- Steps – A step is an individual task that can run commands in a job. A step can be either an action (defined with
- Jobs – Jobs run on a specific runner or Operation System. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the
Pricing
See: About billing for GitHub Actions
You can also host your own runners if needed. See: About self-hosted runners
Also see
Creating Actions
There are three types of actions.
- JavaScript Actions: JavaScript actions run on the host machine. The unit of work is decoupled from the environment. Also see: Creating a JavaScript Action
- Docker Actions: A container action is a container which carries both the unit of work along with the environment and its dependencies packaged up as a container. Also see: Creating a Docker Action
- Composite Run Steps Actions: A composite run steps action allows you to combine multiple workflow run steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands a single step using that action. Also see: Creating a composite run steps action
Both have access to the workspace and the github event payload and context.
Also see: https://github.com/actions/toolkit/tree/master/docs
- Action Types
- Action Debugging
- Using a specific version of action
- About contexts and expressions
- Environment variables
- Commands
::set-env
,::addPath
,::set-output
echo "::echo::on"
andecho "::echo::off"
- Group and Ungroup Log Lines, Log Level, Problem Matchers
- https://github.com/actions/github-script
- https://github.com/actions/toolkit
- https://github.com/actions/upload-artifact
Trigger Workflow
- Use repository_dispatch event to trigger GitHub Actions workflow via GitHub API
- Use workflow_dispatch event to manually trigger workflow
Example Workflow YAML Files
- https://github.com/n3wt0n/HKOSCon2020/tree/master/.github/workflows
- https://github.com/technote-space/gh-actions-template/tree/master/.github/workflows
Workflow syntax
name
The name of your workflow. GitHub displays the names of your workflows on your repository’s actions page. If you omit name
, GitHub sets it to the workflow file path relative to the root of the repository.
on.<push|pull_request>
on.<push|pull_request>
Required The name of the GitHub event that triggers the workflow.
on:
# Trigger the workflow on push or pull request,
# but only for the main branch on changes to files under src/
push:
branches:
- main
# Push events to branches matching refs/heads/releases/10
- 'releases/**'
# You can exclude tags and branches using the ! character. The order that you define patterns matters.
- '!releases/**-alpha'
# Sequence of patterns matched against refs/heads
branches-ignore:
# Push events to branches matching refs/heads/releases/beta/3-alpha
- 'releases/**-alpha'
# Sequence of patterns matched against refs/tags
tags:
- v1 # Push events to v1 tag
# Sequence of patterns matched against refs/tags
tags-ignore:
- v1.* # Push events to tags v1.0, v1.1, and v1.9
paths:
- 'src/**'
- '**.js'
- '!src/docs/**'
paths-ignore:
- 'docs/**'
pull_request:
branches:
- release/**
See more examples: workflow-syntax-for-github-actions#on
on.<event_name>.types
on:
pull_request:
types: [assigned, opened, synchronize, reopened]
on:
pull_request_review:
types: [edited, dismissed]
on.workflow_run
This event occurs when a workflow run is requested or completed, and allows you to execute a workflow based on the finished result of another workflow. For example, if your pull_request
workflow generates build artifacts, you can create a new workflow that uses workflow_run
to analyze the results and add a comment to the original pull request.
The workflow started by the workflow_run
event is able to access the secrets and write tokens used by the original workflow.
on:
workflow_run:
workflows: ["Run Tests"]
branches: [main]
types:
- completed
- requested
See other event examples: events-that-trigger-workflows#webhook-events
env
A map
of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see jobs.<job_id>.env
and jobs.<job_id>.steps.env
.
Also see: default-environment-variables
env:
type: production
jobs:
build:
env:
baseDir: projects
- name: Test1
run: echo $baseDir/$type
- name: Test2 for $type
run: echo ${{ baseDir }}/${{ type }}
- name: Test3 using format
run: echo ${{ format('{0}/{1}', '$baseDir', '$type') }}
Contexts
Contexts (map
or object
) are a way to access information about workflow runs, runner environments, jobs, and steps. Contexts use the expression syntax.
${{ <context> }}
As part of an expression, you may access context information using one of two syntaxes.
- Index syntax:
github['sha']
- Property dereference syntax:
github.sha
In order to use property dereference syntax, the property name must:
- start with
a-Z
or_
. - be followed by
a-Z
0-9
-
or_
.
Literal
As part of an expression, you can use boolean
, null
, number
, or string
data types.
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99-e2 }}
myString: ${{ 'Mona the Octocat' }}
myEscapedString: ${{ 'It''s open source!' }}
Expressions are commonly used with the conditional if
keyword in a workflow file to determine whether a step should run. When an if
conditional is true
, the step will run.
steps:
- uses: actions/hello-world-javascript-action@v1.1
if: ${{ <expression> }}
Built-in Functions
GitHub offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons.
# Object filters
# You can use the * syntax to apply a filter and select matching items in a collection.
fruits = [
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
# The filter fruits.*.name returns the array [ "apple", "orange", "pear" ]
# Returns true if search contains item.
# If search is an array, this function returns true if the item is an element in the array.
# If search is a string, this function returns true if the item is a substring of search.
# This function is not case sensitive. Casts values to a string.
contains( search, item )
contains(github.event.issue.labels.*.name, 'bug')
# Returns true
contains('Hello world', 'llo')
startsWith( searchString, searchValue )
endsWith( searchString, searchValue )
format( string, replaceValue0, replaceValue1, ..., replaceValueN)
# Returns 'Hello Mona the Octocat'
format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')
join( array, optionalSeparator )
# May return 'bug, help wanted'
join(github.event.issue.labels.*.name, ', ')
toJSON(value)
# Might return { "status": "Success" }
toJSON(job)
fromJSON(value)
# Returns a JSON object for value
fromJson(needs.job1.outputs.matrix)
# Calculates an individual SHA-256 hash for each matched file,
# and then uses those hashes to calculate a final SHA-256 hash for the set of files.
hashFiles(path)
# Matches any package-lock.json file in the repository.
hashFiles('**/package-lock.json')
# Creates a hash for any package-lock.json and Gemfile.lock files in the repository.
hashFiles('**/package-lock.json', '**/Gemfile.lock')
# Returns true when none of the previous steps have failed or been canceled.
steps:
...
- name: The job has succeeded
if: ${{ success() }}
# Always returns true, even when canceled.
# A job or step will not run when a critical failure prevents the task from running.
if: ${{ always() }}
# Returns true if the workflow was canceled.
if: ${{ cancelled() }}
# Returns true when any previous step of a job fails.
steps:
...
- name: The job has failed
if: ${{ failure() }}
Also see: context-and-expression-syntax-for-github-actions
defaults
A map
of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see jobs.<job_id>.defaults
.
Actions
actions/first-interaction@v1
An action for filtering pull requests and issues from first-time contributors.
name: FirstPullRequest
on: [pull_request]
jobs:
greeting:
runs-on: ubuntu-latest
steps:
- uses: actions/first-interaction@v1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
issue-message: '# Message with markdown.\nThis is the message that will be displayed on users' first issue.'
pr-message: |-
# Hello
'Message that will be displayed on users' first pr. Look, a `code block` for markdown.'
https://github.com/actions/first-interaction
actions/checkout@v2
Check out multiple repos under workspace directory (e.g. ~/work/myrepo0/myrepo0
).
myrepo1 and myrepo2 will be checked out under ~/work/myrepo0/myrepo0/myrepo1
and ~/work/myrepo0/myrepo0/myrepo2
- uses: actions/checkout@v2
with:
repository: myuser/myrepo1
path: myrepo1
ref: mybranch
ssh-key: ${{ secrets.MY_SSH_KEY }}
- uses: actions/checkout@v2
with:
repository: myuser/myrepo2
path: myrepo2
ref: mybranch
ssh-key: ${{ secrets.MY_SSH_KEY }}
https://github.com/actions/checkout#checkout-v2