Workflow configuration options

Note: GitHub Actions is currently available in public beta, which means you should avoid using it for high-value workflows and content during this beta period.

Features and requirements may change at any time during this period. You can request to join the public beta on the GitHub Actions page. If you're participating in the beta, please contact support if you have any questions.

When creating a workflow, you start with a .github/main.workflow file. You can use any number of workflow and actions blocks in any order in that workflow, and you can configure each one of these blocks using configuration attributes.

Workflow limitations

We currently limit workflows in the following ways:

  • Each workflow can run for up to 58 minutes (including queuing and execution time).
  • Each workflow can run up to 100 actions (including build and other meta steps).
  • Two workflows can be running concurrently per repository.
  • An action can't trigger other workflows. For example, a push, deployment, or any task performed within an action with the provided GITHUB_TOKEN will not trigger a workflow listening on push, deploy, or any other supported action triggers.
  • Docker container logs are limited to a maximum size 64 KB.
  • The list of IP addresses for GitHub Actions outbound traffic is dynamic so we are unable to provide a consistent list of allowed IP addresses.
  • You can execute up to 1000 API requests in an hour across all actions within a repository.

Example workflow

The following example workflow contains one workflow block and two action blocks.

workflow "IDENTIFIER" {
  on = "EVENT"
  resolves = "ACTION2"
}

action "ACTION1" {
  uses = "docker://image1"
}

action "ACTION2" {
  needs = "ACTION1"
  uses = "docker://image2"
}

In this example, the workflow invokes ACTION2 using resolves, but because it needs ACTION1, the ACTION1 block executes first. ACTION2 will execute once ACTION1 has successfully completed. For more information on why this happens, see "Workflow attributes" and "Actions attributes" below.

Workflow blocks

A workflow file may contain any number of workflow blocks, each with a unique identifier and the attributes outlined in the workflow attributes table.

Example workflow block

workflow "IDENTIFIER" {
  on = "EVENT"
  resolves = ["ACTION1", "ACTION2"]
}

Example scheduled workflow block

This example triggers the workflow every 15 minutes.

workflow "IDENTIFIER" {
  on = "schedule(*/15 * * * *)"
  resolves = ["ACTION1", "ACTION2"]
}

Workflow attributes

Name Description
on Identifies the name of the GitHub event that triggers the workflow or schedules the workflow to run.
For many events, the version of the workflow file used will depend on the event that triggers the workflow. For example, when triggering a push event, the workflow file from the latest commit associated with the push is used. But when triggering an issue_comment event, the workflow file in the default branch (usually master) will be used.
You can schedule the workflow to run using POSIX cron syntax. A scheduled workflow will use the workflow file checked into the default branch (usually master). See "Scheduling a workflow" for examples using cron syntax.
resolves Identifies the action(s) to invoke. Can be a string or an array of strings. Any dependencies of the named action listed in the needs attribute are also invoked. In the example workflow above, ACTION2 runs first via the resolves attribute. When more than one action is listed, like the example workflow block above, the actions are executed in parallel.

Action blocks

A workflow file may contain up to 100 action blocks. Action blocks must have a unique identifier and must have a uses attribute.

Note: GitHub adds some action blocks internally that count towards the maximum number of action blocks.

Example action block

action "IDENTIFIER" {
  needs = "ACTION1"
  uses = "docker://image2"
}

Actions attributes

Name Description
needs Identifies actions that must complete successfully before this action will be invoked. It can be a string or an array of strings. In the example workflow above, ACTION2 is executed after ACTION1 is successfully completed.
Note: When actions with a common needs dependency run in parallel and one action fails, the remaining actions are cancelled automatically.
uses The Docker image that will run the action. For example, uses = "node:10". See "Using a Dockerfile image in an action" for more examples.
runs Specifies the command to run in the docker image. If runs is omitted, the command specified in the Dockerfile ENTRYPOINT instruction will execute. Use the runs attribute when the Dockerfile does not specify an ENTRYPOINT or you want to override the ENTRYPOINT command.

The runs attribute does not invoke a shell by default. To use environment variables with the runs instruction, you must include a shell to expand the variables, for example:
runs = ["sh", "-c", "echo $GITHUB_SHA"]

Using runs = "echo $GITHUB_SHA" will not print the value stored in the $GITHUB_SHA, but will instead print "$GITHUB_SHA."
args The arguments to pass to the action. The args can be a string or array. If you provide args in a string, the string is split around whitespace. For example, args = "container:release --app web" or args = ["container:release", "--app", "web"]
env The environment variables to set in the action's runtime environment. If you need to pass environment variables into an action, make sure your action runs a command shell to perform variable substitution. For example, if your runs attribute is set to "sh -c", args will be run in a command shell. Alternatively, if your Dockerfile uses an ENTRYPOINT to run the same command ("sh -c"), args will execute in a command shell. See ENTRYPOINT for more details.
secrets Specifies the names of the secret variables to set in the runtime environment, which the action can access as an environment variable. For example, secrets = ["SECRET1", "SECRET2"]. The values of secrets must be set in the visual workflow editor or in your repository's "Settings" tab. Production secrets should not be stored in the API during the limited public beta period. See "Storing secrets" for more details.

Using a Dockerfile image in an action

When creating an action block, you can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image. An action block refers to the images using the uses attribute. It's strongly recommended to include the version of the action you are using by specifying a SHA or Docker tag number. If you don't specify a version and the action owner publishes an update, it may break your workflows or have unexpected behavior. Here are some examples of the how you can refer to an action on GitHub and Docker:

Template Description
{user}/{repo}@{ref} A specific branch, ref, or SHA in a public GitHub repository.
Example: actions/heroku@master
{user}/{repo}/{path}@{ref} A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.
Example: actions/aws/ec2@v2.0.1
./path/to/dir The path to the directory that contains the action in your workflow's repository.
Example: ./.github/action/my-action
docker://{image}:{tag} A Docker image published on Docker Hub.
Example: docker://alpine:3.8
docker://{host}/{image}:{tag} A Docker image in a public registry.
Example: docker://gcr.io/cloud-builders/gradle

Events supported in workflow files

The following table shows the events currently supported in workflow files, and whether the version of the workflow file is the SHA of the default branch or event-specific. For more on GitHub webhook events, see "Events."

When a GitHub action runs, GitHub clones the repository contents and sets the commit SHA (GITHUB_SHA) and GitHub ref (GITHUB_REF) environment variables. See "Environment variables" for more details.

The commit that GitHub checks out depends on the event that triggered the action. The GITHUB_SHA and GITHUB_REF columns in the table below describe how GitHub selects the commit SHA and GitHub ref:

  • GitHub reads an event-specific GITHUB_SHA or GITHUB_REF directly from the webhook payload.
  • When an event has a GITHUB_SHA that is resolved by a branch or tag, GitHub uses the latest commit SHA of the branch in the webhook payload.
  • When an event has a default GITHUB_REF, GitHub uses the latest commit SHA of the repository's default branch.
Event name GITHUB_SHA GITHUB_REF Event description
check_run Check run commit Check suite branch Triggered when a check run is created, rerequested, completed, or has a requested_action.
check_suite Check suite commit Check suite branch Triggered when a check suite is completed, requested, or rerequested.
commit_comment Commit that was commented on n/a Triggered when a commit comment is created.
create Resolved by branch or tag Branch or tag created Represents a created repository, branch, or tag.
delete Last commit on default branch Default branch Represents a deleted branch or tag.
deployment Commit to be deployed Branch/tag to be deployed (empty if commit) Represents a deployment. Deployments created with a commit SHA may not have a GitHub ref.
deployment_status Commit being deployed Branch/tag to be deployed (empty if commit) Represents a deployment status. Deployments created with a commit SHA may not have a GitHub ref.
fork Last commit on default branch Default branch Triggered when a user forks a repository.
gollum Last commit on default branch Default branch Triggered when a Wiki page is created or updated.
issue_comment Last commit on default branch Default branch Triggered when an issue comment is created, edited, or deleted.
issues Last commit on default branch Default branch Triggered when an issue is opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, unlabeled, locked, unlocked, milestoned, or demilestoned.
label Last commit on default branch Default branch Triggered when a repository's label is created, edited, or deleted.
member Last commit on default branch Default branch Triggered when a user accepts an invitation or is removed as a collaborator to a repository, or has their permissions changed.
milestone Last commit on default branch Default branch Triggered when a milestone is created, closed, opened, edited, or deleted.
page_build The commit being built n/a Triggered on push to a GitHub Pages enabled branch (gh-pages for project pages, master for user and organization pages).
project Last commit on default branch Default branch Triggered when a project is created, updated, closed, reopened, or deleted.
project_card Last commit on default branch Default branch Triggered when a project card is created, edited, moved, converted to an issue, or deleted.
project_column Last commit on default branch Default branch Triggered when a project column is created, updated, moved, or deleted.
public Last commit on default branch Default branch Triggered when a private repository is made public.
pull_request Resolved by branch Last commit on branch, or base branch if from a fork Triggered when a pull request is assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, synchronize, ready_for_review, locked, unlocked or when a pull request review is requested or removed. See below to learn how this event works with forked repositories.
pull_request_review_comment Resolved by branch Last commit on branch, or base branch if from a fork Triggered when a comment on a pull request's unified diff is created, edited, or deleted (in the Files Changed tab). See below to learn how this event works with forked repositories.
pull_request_review Resolved by branch Last commit on branch, or base branch if from a fork Triggered when a pull request review is submitted into a non-pending state, the body is edited, or the review is dismissed. See below to learn how this event works with forked repositories.
push Commit pushed, unless deleting a branch (when it's the default branch) Updated ref Triggered on a push to a repository branch. Branch pushes and repository tag pushes also trigger webhook push events. This is the default event.
repository_dispatch Resolved by branch Branch that received dispatch Any time another user or app triggers the event.
release Resolved by tag Tag of release Triggered when a release is published, unpublished, created, edited, deleted, or prereleased.
scheduled Last commit on default branch Default branch When the scheduled workflow is set to run. A scheduled workflow uses POSIX cron syntax. See "Scheduling a workflow" for more details.
status Commit that changed status n/a Triggered when the status of a Git commit changes.
watch Last commit on default branch Default branch Triggered when someone stars a repository.

Pull request events for forked repositories

When a pull request is opened from a forked repository, the pull request will be opened on the base repository by default. The pull_request event is sent to the base repository, with no pull request events on the forked repository because a forked repository does not carry over all of the webhook configuration of the original repository. If you intend to use the pull_request event to trigger CI tests, it's recommended to listen to the push event.

Pull request with base and head branches in the same repository

  • The repository receives a pull_request event where the SHA is the latest commit of head branch and the ref is the head branch.

Pull request with base and head branches in different repositories

  • The base repository receives a pull_request event where the SHA is the latest commit of base branch and ref is the base branch.