Creating and cancelling a workflow

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.

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. This example is also available as a course on GitHub Learning Lab. 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.

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