How to Run an Autonomous AI Agent on GitHub Actions

TL;DR: Running an autonomous AI agent on GitHub Actions means treating a scheduled workflow as the agent's runtime - a cron trigger checks out the repo, launches an agent CLI against a prompt file, and the run writes its own state back as committed files. There is no server to patch and no polling loop to keep alive; GitHub's own scheduler is the only infrastructure required.

A cron daemon or a worker process needs monitoring, restarts, and somewhere to run. A GitHub Actions workflow already covers all three: a schedule: trigger replaces the cron daemon, a fresh VM replaces the worker, and the Actions log replaces application logging you would otherwise have to ship somewhere. On a public repository the compute minutes are free, so the only recurring cost is the LLM calls each run makes.

An unattended agent task can be a single Markdown file: a small frontmatter block, then a plain-language prompt. Nothing else defines what a run does.

---
name: digest
category: basics                 # which pack it belongs to
description: Generate and send a digest on a configurable topic
requires: [XAI_API_KEY?]         # ? = optional key, bare = required
var: ""                          # per-run input - "solana", "rust", "AI agents"...
mode: write
---

The skill file itself carries no schedule. Cron lives in a separate config that the workflow reads on every tick:

skills:
  token-movers: { enabled: true, schedule: "30 12 * * *", model: "claude-haiku-4-5-20251001" }

The expression above only decides when one skill is due. A second, coarser cron controls how often the workflow itself wakes up to check the list - editing it trades responsiveness against Actions minutes:

schedule:
  - cron: '*/5 * * * *'    # every 5 min (default)
  - cron: '*/15 * * * *'   # every 15 min (saves Actions minutes)
  - cron: '0 * * * *'      # hourly (most conservative)

A workflow run has no disk that survives past the job - every tick starts from a clean checkout. The fix is to commit state instead of storing it locally: run outcomes land in a tracked JSON file, and working notes live as plain files in the repo, so the next run reads the same git history rather than a database it would have to stand up separately. An append-only GitHub Issue is a documented alternative backend for the same state, for anyone who wants to avoid file-churn commits.

A cron job that fires a prompt on a timer is scheduled, not autonomous - it still needs a human to notice when it breaks. Closing that gap takes a second loop watching the first: a health pass classifies every run and opens an issue when one degrades, and a separate repair pass reads that issue and ships a fix as a pull request. The autonomy is in the loop, not in the trigger.

On a public repository, Actions minutes are unlimited and free, so the only real cost is the model calls each run makes. Private repos get 2,000 free minutes a month on the Free plan (3,000 on Pro/Team, then $0.008/min overage) - lowering the tick frequency in the scheduler block above is the direct lever if that budget is tight.

How do I run an autonomous AI agent on GitHub Actions?

Fork an agent framework like aeon, put a cron line in the workflow, and let a scheduled job check out the repo and run the agent CLI against your prompt file. GitHub's scheduler fires each run; the run commits its own state back. No server, no daemon.

How often can a GitHub Actions cron trigger an agent?

As often as every five minutes with */5 * * * *. GitHub schedules on a best-effort basis and can delay ticks under load, so treat the cadence as a floor, not a guarantee. Widen the interval to save Actions minutes.

Where does the agent store state between runs?

In the repo. A workflow run's disk is wiped when the job ends, so outcomes land in a tracked JSON file and working notes commit as plain files - the next run reads git history. An append-only GitHub Issue is a documented alternative backend.

Is it free to schedule an agent on GitHub Actions?

On a public repo, Actions minutes are unlimited and free, so you only pay for the model calls. Private repos get 2,000 free minutes a month on Free (3,000 on Pro/Team, then $0.008/min); lowering the tick frequency is the direct cost lever.

Set up aeon - a fork, a couple of secrets, and the schedule runs on your own GitHub account. For the architecture behind background-first agents, see the agent that runs while you sleep and the open-source framework overview.