This article was last updated on January 12, 2025, to include advanced techniques for configuring cron schedules in GitHub Actions, such as handling timezone conversions, scheduling workflows with multiple conditions, and debugging inactive or misconfigured schedules, along with simplified explanations to enhance clarity.
What is GitHub Actions cron?
GitHub Actions cron is the feature that allows you to schedule the execution of workflows automatically whenever they reach a certain time. In other words, this is much like setting up bill payments: you set this once, and then it will routinely run on time without your needing to interfere. You define the schedule using cron syntax, for instance, '30 5 * * *' - runs every day at 5:30 AM UTC.
After years of automating the CICD pipeline, I must confidently say scheduled workflows are amongst those powerful and, at the same time, very misunderstood GitHub Actions features. I recall once trying to do a nightly build-the first time was hours into debugging as to why my workflow was not running on schedule. Spoiler alert-just forgot about conversion to UTC.
Steps we will cover in this article:
- How to Use Cron Syntax in GitHub Actions
- GitHub Actions Cron Schedule Builder
- Basic GitHub Actions Schedule Examples
- Common GitHub Actions Schedule Problems
- GitHub Actions Schedule Best Practices
- How to Debug GitHub Actions Schedules
- Cron Syntax Field Values
- Conclusion
How to Use Cron Syntax in GitHub Actionsโ
Cron syntax: Think of it in terms of trying to set the alarm clock radio. Just like your alarm must have time to awaken, cron requires the additional five to let it know just at which time:
Here is how I break it down:
# Format: minute hour day_of_month month day_of_week
'30 5 * * *' # Runs at 5:30 AM UTC every day
It's like saying: "Wake me up at 5:30 AM every day" - the asterisks mean "every" for that position.
GitHub Actions Cron Schedule Builderโ
I've put together the following interactive tool to help you visualize and craft cron schedules. Simply select the schedule you wish to implement, and it will generate the appropriate syntax in cron:
Cron Schedule Builder
0 0 * * *
Runs every day at 12:00 AM UTC
Basic GitHub Actions Schedule Examplesโ
Let me share some basic examples I use daily. These are perfect for getting started with scheduled workflows:
How to Run Daily Code Cleanup?โ
It basically helps you keep your repo clean by automatically removing those pesky temporary files and old logs that pile up.
name: Daily Code Cleanup
on:
schedule:
- cron: '0 0 * * *' # Every day at midnight UTC
jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Remove old files
run: |
find . -type f -name "*.tmp" -mtime +7 -delete
find . -type f -name "*.log" -mtime +7 -delete
How to Schedule Weekly Dependency Updates?โ
You know how annoying it is to manually check for outdated packages, right? This workflow does all that heavy lifting for you every Monday morning. It'll check your dependencies and let you know if anything needs updating.
name: Weekly Dependency Check
on:
schedule:
- cron: '0 9 * * 1' # Every Monday at 9 AM UTC
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Check for updates
run: |
npm outdated
npm audit
How to Generate Monthly Reports Automatically?โ
This is a real time-saver! Instead of scrambling at the end of each month to put together reports, this workflow automatically generates them and even emails them out.
name: Monthly Report
on:
schedule:
- cron: '0 0 1 * *' # First day of every month
jobs:
report:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Generate report
run: |
echo "Generating monthly report..."
./scripts/generate-report.sh
- name: Send email
uses: dawidd6/action-send-mail@v3
with:
server_address: smtp.gmail.com
server_port: 465
username: ${{ secrets.EMAIL_USERNAME }}
password: ${{ secrets.EMAIL_PASSWORD }}
subject: Monthly Report
body: Monthly report attached
attachments: ./report.pdf