Schedule your GitHub Actions workflows to run at a future date and time! 🤯

This works using the schedule event to poll GitHub variables which are used as our database for scheduling.

flowchart LR
    A([`workflow_dispatch`]) --> H[Create scheduled workflow]
    W([`schedule`]) ---> I
    B([`other`]) ---> I
    H --> I[Fetch scheduled workflows]
    I --> P((For Each\nscheduled\nworkflow))
    P --> Q{Is it time to run\nscheduled workflow?}
    Q --> |yes| R[Run scheduled workflow]
    R --> S[Delete scheduled workflow]
    S --> V{Have we waited\n`wait-ms`?}
    V --> |no| T[Wait\n`wait-delay-ms`]
    T --> I
    V --> |yes| U[Write job summary]
    Q --> |no| V

Create a workflow (eg: .github/workflows/schedule.yml) and copy the example below. Ensure you've setup the authentication and inputs correctly.

• Create a GitHub App with the actions & actions_variables scope.
• Use the actions/create-github-app-token action to create a GitHub App token to generate a token.

You need to create a Personal Access Token (PAT) with the repo scope and add it to your repository secrets.

The token must have the following permission set:

• actions_variables:write
• actions:write

This workflow runs on a schedule event every hour and spends <1min checking the schedule for any pending workflows to run.

To schedule a workflow, manually do a workflow_dispatch by going to "Actions > 📅 Schedule Workflow Dispatch", type when you want the workflow to run, and click Run workflow.

• Replace the workflow input with the name, path, or id of the workflow you want to run
• Change the timezone input to your timezone

name: 📅 Schedule Workflow Dispatch
on:
  schedule:
    - cron: '0 */1 * * *' # every hour
  workflow_dispatch:
    inputs:
      date:
        description: 'Date to run the workflow'
        required: true
        type: string
        default: 'in 1 hour'
concurrency:
  group: schedule${{ github.event.inputs.date }}
  cancel-in-progress: true

jobs:
  schedule:
    name: 📅 Schedule
    runs-on: ubuntu-latest
    steps:
      - uses: austenstone/[email protected]
        with:
          github-token: ${{ secrets.TOKEN }}
          date: ${{ github.event.inputs.date }}
          workflow: 'basic.yml'
          timezone: 'US/Eastern' # US/Central, US/Pacific
          wait-ms: 45000

The timezone is set to EST by default. You can change this to your timezone. EX: US/Central, US/Pacific, etc.

          timezone: 'US/Eastern'

The schedule event is used to check for scheduled workflow runs. You can change the cron to run at a different interval.

on:
  schedule:
    - cron: '0 */1 * * *'

The action also has the ability to continue running the workflow and polling for a specific amount of time. This is useful if you want to run the workflow at a specific time and then continue running the workflow for a specific amount of time.

In the example below we spend 5 minutes checking the schedule every 20 seconds:

        with:
          wait-ms: 300000 # Check for 5 minutes
          wait-delay-ms: 20000 # Wait 20 seconds between checks

Pass in the workflow you want to run. This can be the name, path, or id of the workflow.

          workflow: 'basic.yml'

You could provide options for workflows to run. This does interfere with the workflow inputs you might want to pass in.

      workflow:
        description: 'Workflow to run at schedule time'
        required: true
        type: choice
        options:
          - 'basic.yml'
          - 'codeql.yml'
...
        with:
          workflow: ${{ inputs.workflow }}

You can provide the workflow_dispatch inputs you want to provide by using the inputs input.

        with:
          inputs: '{"name": "Austen"}'

or from the inputs themselves.

        with:
          inputs: ${{ toJson(github.event.inputs) }}

Various inputs are defined in action.yml:

To get more help on the Actions see the documentation.