Workflow configuration options

Note: GitHub Actions are currently available as a limited public beta, which means you should avoid using it for high-value workflows and content during this beta period. Creating workflows that use GitHub Actions is limited to private repositories during the limited public beta.

Features and requirements may change at any time during this period. You can request to join the limited 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.
  • Any task performed from within an action cannot trigger further actions. For example, a push, deployment or any task created with the provided GITHUB_TOKEN will not trigger a workflow listening on push, deploy, or any of the other supported action triggers.
  • Note: Docker container logs are limited to a maximum size 64 KB.

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"]
}

Workflow attributes

Name Description
on Identifies the name of the GitHub event that triggers the workflow. 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.
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.
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 Event specific Event specific Any time a check run is created, rerequested, or has a requested_action.
check_suite Event specific Event specific Any time a check suite is completed, requested, or rerequested.
commit_comment Event specific n/a Any time a commit comment is created.
create Resolved by branch or tag Event specific Any time a branch or tag is created.
delete Resolved by branch Default branch Any time a branch or tag is deleted.
deployment Event specific Event specific Any time a repository has a new deployment created from the API. Ref might be N/A if the deployment was created with a SHA.
deployment_status Event specific Event specific Any time a deployment for a repository has a status update from the API. Ref might be N/A if the deployment was created with a SHA.
fork Resolved by branch Default branch Any time a repository is forked.
gollum Resolved by branch Default branch Any time a Wiki page is updated.
issue_comment Resolved by branch Default branch Any time a comment on an issue is created, edited, or deleted.
issues Resolved by branch Default branch Any time an issue is assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed, or reopened.
label Resolved by branch Default branch Any time a label is created, edited, or deleted.
member Resolved by branch Default branch Any time a user accepts an invitation or is removed as a collaborator to a repository, or has their permissions modified.
milestone Resolved by branch Default branch Any time a milestone is created, closed, opened, edited, or deleted.
page_build Event specific n/a Any time a pages site is built or results in a failed build.
project Resolved by branch Default branch Any time a project is created, edited, closed, reopened, or deleted.
project_card Resolved by branch Default branch Any time a project card is created, edited, moved, converted to an issue, or deleted.
project_column Resolved by branch Default branch Any time a project column is created, edited, moved, or deleted.
public Resolved by branch Default branch Any time a repository changes from private to public.
pull_request Event specific Event specific Any time a pull request is assigned, unassigned, review_requested, review_request_removed, labeled, unlabeled, opened, edited, closed, reopened, or synchronized (updated due to a new push in the branch that the pull request is tracking). See "Pull request events for forked repositories" to learn how pull_request events work with forked repositories.
pull_request_review_comment Event specific Event specific Any time a comment on a pull request's unified diff is created, edited, or deleted (in the Files Changed tab).
pull_request_review Event specific Event specific Any time a pull request review is submitted, edited, or dismissed.
push Event specific unless deleting a branch (when it's the default branch) Event specific Any git push to a repository, including editing tags or branches. Commits via API actions that update references are also counted. This is the default event.
repository_dispatch Resolved by branch Event specific Any time another user or app triggers the event.
release Resolved by tag Event specific Any time a release is published in a repository.
status Event specific n/a Any time a repository has a status update from the API.
watch Resolved by branch Default branch Any time a user 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.