Creating and cancelling a workflow

New release: GitHub Actions is now available in a new limited public beta. This version offers a new workflow configuration and built-in continuous integration and continuous deployment capabilities. We strongly recommend you avoid using it for high-value workflows and content during this public beta period. To request to join the limited public beta, see the GitHub Actions page. For more information, see "About GitHub Actions" in the GitHub Help documentation.

GitHub Support will only provide support for the YAML syntax and no longer provides support for the HCL syntax.

If you participated in the limited public beta and created workflows with the HCL syntax GitHub Actions, you will need to upgrade to the new limited public beta that uses YAML syntax. When your repository is eligible to upgrade, you'll see an invitation in your repository. You must accept the invitation before you can use the new limited public beta.

Once you've upgraded, any workflows that you created with the HCL syntax will need to be updated to the new YAML syntax. To automatically convert your workflows, see "Migrating GitHub Actions from HCL syntax to YAML syntax" in the GitHub Help documentation.

Using the visual or file editor, you can create a workflow that contains GitHub Actions, and their relationships to each other. Once you've created a .github/main.workflow file, you need to add workflow and action blocks. You can add content to these blocks using "Workflow configuration options." For more information, see "Creating a workflow with GitHub Actions" in the GitHub Help documentation.

Hello world workflow example

This example manually creates a workflow and an action, rather than using the visual editor. The workflow in this example uses the action created in the "Hello world action example" to write values to standard output (stdout).

The action writes any values passed in the args action attribute to stdout.

Here's an overview of the file hierarchy you'll use:

|-- hello-world (repository)
|   |__ .github
|       |__ main.workflow
|   |__ action-a
|       │__  Dockerfile
|       |__  entrypoint.sh  
|

You can use any repository name, or you can create a new private repository called hello-world. To create the action, add these two files:

./action-a/Dockerfile

FROM debian:9.5-slim

LABEL "com.github.actions.name"="Hello World"
LABEL "com.github.actions.description"="Write arguments to the standard output"
LABEL "com.github.actions.icon"="mic"
LABEL "com.github.actions.color"="purple"

LABEL "repository"="http://github.com/octocat/hello-world"
LABEL "homepage"="http://github.com/actions"
LABEL "maintainer"="Octocat <octocat@github.com>"

ADD entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

./action-a/entrypoint.sh

#!/bin/sh -l

sh -c "echo $*"

Your code must be executable. Make sure the entrypoint.sh file has execute permissions before using it in a workflow. You can modify the permission from your terminal using this command:

chmod +x entrypoint.sh

You'll need one workflow block and one action block for this example.

Your workflow block will execute anytime code is pushed to your repository, using the push event. The workflow selects the action to execute using the resolves attribute.

The action block uses action-a by referencing the path to the action's directory, relative to your hello-world repository.

Use the env action attribute to create an environment variable that will be available to your action in the runtime environment. Finally, you'll pass a string to the action in the args attribute. The args you pass are appended to the echo command in entrypoint.sh and run in a command shell. This allows you to use environment variables in the args attribute. See "ENTRYPOINT" for more about how the entrypoint.sh file works.

main.workflow

workflow "New workflow" {
  on = "push"
  resolves = ["Hello World"]
}

action "Hello World" {
  uses = "./action-a"
  env = {
    MY_NAME = "Mona"
  }
  args = "\"Hello world, I'm $MY_NAME!\""
}

If you add these three files to your repository using the file structure above, an action will run the next time you push code to your repository. To see the action, click the "Actions" tab in your repository. From there you will see the actions that have run, and you can click on the action's "Log" link to view details.

View an action's log

You should see the string "Hello world, I'm Mona!" printed at the bottom to stdout.

Actions successful log file

Viewing an action's check suite

GitHub Actions use the Checks API to output the Docker logs and status of a workflow. Each time a workflow runs in your repository a new check suite called "GitHub Actions" gets created. The check suite contains a check run for each action in the workflow.

You can view a workflow's history and status in the Actions tab of your repository. In the lower right corner of the action you can find a link to the action's check run page. When a workflow runs on the base branch of your repository, use the Log link in the Actions tab to view a check run for an action.

GitHub action log button

When the action runs on a branch that is part of a pull request, you can access the check suite and its check runs from the Checks tab of the pull request.

Viewing the check suite for a GitHub Actions workflow

Scheduling a workflow

You can schedule a workflow to run at specific times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch.

Cron syntax

You set the time of the scheduled event using cron syntax, which has five fields separated by a space. For example, * * * * *. Each field represents a unit of time:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

You can use these operators in any of the five fields:

Operator Description Example
* Any value * * * * * runs every minute of every day.
, Value list separator 2,10 4,5 * * * runs at minute 2 and 10 of the 4th and 5th hour of every day.
- Range of values 0 4-6 * * * runs at minute 0 of the 4th, 5th, and 6th hour.
/ Step values 20/15 * * * * runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50).

Note: The non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly, and @reboot are not supported by GitHub Actions.

You can use crontab guru to help generate your cron syntax and confirm what time it will run, or start from the list of crontab guru examples.

Example workflow

This example triggers the workflow every 15 minutes:

workflow "New workflow" {
  on = "schedule(*/15 * * * *)"
  resolves = ["Hello World"]
}

To learn more about creating workflow files, see "Workflow configuration options."

Cancelling a workflow

You can cancel an actively running workflow from the Actions tab of your repository. Cancelling a workflow will cancel all actions that are a part of that workflow.

To cancel the workflow, click the Cancel workflow button in the Actions tab. To confirm that you would like to cancel the workflow and all of its actions, click Yes, cancel it.

Cancel GitHub Actions workflow button

You will see a confirmation that the workflow was cancelled in the Actions tab of your repository.

GitHub Action workflow cancellation confirmation