How to Run a Scheduled Cleanup Job in GitHub Actions

A schedule trigger runs maintenance jobs on a cron cadence with no human in the loop.

Use on.schedule with a cron expression. The job runs on the default branch at the interval you set.

Steps

• Add an on.schedule block with a cron expression in UTC.
• Grant only the permissions the cleanup needs.
• Run your prune logic, e.g. deleting old workflow run artifacts.

Workflow

on:
  schedule:
    - cron: '0 3 * * 0'
permissions:
  actions: write
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - run: gh api -X DELETE "repos/${{ github.repository }}/actions/caches?key=stale-"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gotchas

• Scheduled runs only fire from the default branch.
• Cron is UTC; account for the offset when picking a time.

Related guides