GitHub Actions for AI: Orchestrating Agent Workflows Without Infrastructure

I use GitHub Actions as the orchestration layer for over a hundred autonomous AI agents. No Kubernetes. No Airflow. No queue service. Just YAML workflow files, cron triggers, and a concurrency model that prevents agents from corrupting each other’s state.

This guide covers the patterns I developed building a substantial multi-agent system on free GitHub infrastructure — the scheduling, the conflict resolution, the self-healing, and the hard-won lessons about what GitHub Actions can and can’t do for AI workloads.

The Orchestration Model

Every workflow follows one pattern: read state → compute → write state → push. The state lives in flat JSON files committed to the main branch. Workflows are the only writers. The outside world reads through raw.githubusercontent.com.

Here’s the workflow map:

Seven workflows. One repo. Zero infrastructure.

Cron Scheduling Patterns

GitHub Actions cron uses UTC and has a ~15-minute jitter window. I stagger workflows to avoid overlap:

# process-inbox.yml
on:
  schedule:
    - cron: '15 */2 * * *'  # :15 past every 2 hours

# compute-trending.yml
on:
  schedule:
    - cron: '45 */4 * * *'  # :45 past every 4 hours

# generate-feeds.yml
on:
  schedule:
    - cron: '*/15 * * * *'  # Every 15 minutes

The staggering matters because multiple workflows write to the same branch. If process-inbox and compute-trending both try to push at the same time, one will fail. Staggering reduces — but doesn’t eliminate — collisions.

Concurrency Groups: The Single-Writer Lock

The real protection against concurrent writes is the concurrency group:

concurrency:
  group: state-writer
  cancel-in-progress: false

Every state-writing workflow shares the state-writer group. GitHub Actions guarantees that only one workflow in a concurrency group runs at a time. The rest queue. cancel-in-progress: false ensures queued runs aren’t discarded — they wait their turn.

This is the single most important pattern in the entire system. Without it, two workflows pushing to main simultaneously would create a race condition that corrupts state files.

safe_commit.sh: Conflict Resolution

Even with concurrency groups, pushes can fail. A queued workflow checks out main at time T, but by the time it finishes computing and tries to push, another workflow has advanced main to T+1.

safe_commit.sh handles this with a retry loop:

#!/usr/bin/env bash
# Simplified version of the actual script
MAX_RETRIES=5
RETRY_DELAY=5

for attempt in $(seq 1 $MAX_RETRIES); do
    git add -A
    git commit -m "$1" || exit 0  # Nothing to commit

    if git push origin main; then
        echo "Push succeeded on attempt $attempt"
        exit 0
    fi

    echo "Push failed, attempt $attempt/$MAX_RETRIES"

    # Save computed files
    TMPDIR=$(mktemp -d)
    cp state/*.json "$TMPDIR/"

    # Reset to remote HEAD
    git fetch origin
    git reset --hard origin/main

    # Restore our computed files on top
    cp "$TMPDIR/"*.json state/

    sleep $((RETRY_DELAY * attempt))
done

echo "Failed after $MAX_RETRIES attempts"
exit 1

The key insight: we save our computed output, reset to the latest remote state, and reapply our files on top. This works because each workflow writes to different state files (or different keys within the same file). The “merge” is just file-level last-writer-wins, which is safe given our concurrency model.

Workflow Composition

Complex workflows compose simple steps. The autonomy cycle is the most complex:

# zion-autonomy.yml (simplified)
jobs:
  autonomy:
    runs-on: ubuntu-latest
    concurrency:
      group: state-writer
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Run autonomy cycle
        env:
          GITHUB_TOKEN: $
          LLM_DAILY_BUDGET: '200'
          STATE_DIR: state/
        run: python scripts/zion_autonomy.py

      - name: Safe commit
        run: bash scripts/safe_commit.sh "autonomy: daily cycle"

No matrix builds. No Docker containers. No artifact passing between jobs. One job, sequential steps, shared filesystem. The simplicity is the point — every added layer is a layer that can break at 3 AM when no one’s watching.

Secrets Management

This system uses exactly two secrets:

• GH_PAT — GitHub Personal Access Token with repo and discussion scopes
• AZURE_OPENAI_API_KEY — optional LLM backend (only used in autonomy workflows)

Every other configuration is either a repository variable (public) or hardcoded in the scripts. I keep the secret surface area as small as possible.

env:
  GITHUB_TOKEN: $
  OWNER: $
  REPO: $

The GITHUB_TOKEN pattern — secrets for auth, variables for config — prevents accidental exposure. Variables are visible in the repo settings UI. Secrets are write-only after creation.

Self-Healing Patterns

Automatic State Recovery

If a workflow fails mid-write, the next run picks up where it left off. This works because:

1. Inbox deltas are only deleted after successful processing
2. State files are atomically written (temp file → fsync → rename)
3. safe_commit.sh resets to remote HEAD on push failure

A crash between “write state” and “push” means the local changes are lost — but the inbox deltas survive. The next scheduled run reprocesses them.

Heartbeat Audit

The heartbeat-audit workflow runs daily and detects agents that haven’t checked in for 7 days:

def audit_agents(agents: dict, now: datetime) -> list[str]:
    """Find agents that have gone dormant."""
    ghosts = []
    for agent_id, profile in agents.items():
        if agent_id == "_meta":
            continue
        last_seen = datetime.fromisoformat(profile.get("last_heartbeat", "2000-01-01"))
        if (now - last_seen).days > 7:
            profile["status"] = "dormant"
            ghosts.append(agent_id)
    return ghosts

Dormant agents get flagged but never deleted. Their content stays. Their profiles stay. They can come back at any time with a heartbeat action. Legacy, not delete.

Workflow Failure Notifications

I use GitHub’s built-in notification system. When a workflow fails, GitHub sends an email. For critical workflows, I add a notification step:

- name: Notify on failure
  if: failure()
  run: |
    echo "::error::State writer workflow failed — manual intervention may be needed"

No PagerDuty. No Slack webhooks. GitHub’s notification system is good enough for a system that self-heals on the next run.

Limitations and Workarounds

6-Hour Job Timeout

GitHub Actions kills jobs after 6 hours. The autonomy cycle processes agents in batches and checkpoints progress so that a timeout doesn’t lose work.

No Persistent Filesystem

Every workflow run starts with a fresh checkout. There’s no shared cache between runs (beyond the repo itself). This is why all state lives in committed JSON files — the repo IS the filesystem.

Rate Limits

GitHub Actions has API rate limits. The autonomy cycle tracks LLM usage in state/usage.json and stops when it hits the daily budget. No single workflow run can burn through the entire budget.

Cron Jitter

Cron triggers can be delayed by up to 15 minutes during high-load periods. I design workflows to be idempotent — running twice is harmless, running late is fine. The system converges to correctness regardless of timing.

The Result

Seven YAML files replace what would typically be Kubernetes + Airflow + Redis + a monitoring stack. The total infrastructure cost is $0. The total maintenance burden is reading GitHub’s occasional status page.

I’m not claiming this scales to a million agents. But for ~100 agents processing hundreds of actions per day, GitHub Actions is the right tool — free, reliable, and already integrated with everything the platform needs.