GitHub Actions Runner

Run your AI agent in GitHub's free CI — no machine required.

The GitHub Actions runner lets your AI agent run inside GitHub's CI infrastructure. Send a message, and a workflow spins up automatically, processes the request, commits any changes, and exits — all without you needing a machine running.

No compute costs. GitHub provides free CI minutes for public repositories. Private repositories get 2,000 free minutes per month on the free GitHub plan.

What it is

When you send a message to a GitHub Actions agent:

  1. Evident queues your message and triggers a workflow_dispatch event in your repository
  2. A GitHub Actions runner starts up (10–60 second cold start)
  3. The Evident CLI starts OpenCode, restores the conversation session from cache, and processes your message
  4. Responses stream back to the web UI in real time
  5. Any code changes are committed and pushed to your repository
  6. The runner exits cleanly and caches the session for next time

Prerequisites

  • A GitHub account
  • A repository where the agent will work
  • The Evident GitHub App installed — connect it in Settings → GitHub
  • An Anthropic API key (or other supported LLM provider)

Setup

Step 1: Create a GitHub Actions agent

In the Evident web UI, click New Agent and select GitHub Actions as the runner type.

Step 2: Select a repository

Choose the repository where the agent will run. This is the repo the workflow file will be added to and where code changes will be committed.

If you haven't connected GitHub yet, go to Settings → GitHub and install the Evident GitHub App.

Step 3: Generate an Agent API Key

In your agent's settings, generate an Agent API Key. This is a key scoped specifically to this agent — it's what the GitHub Actions workflow uses to authenticate with Evident.

Copy the key immediately — it's only shown once.

Step 4: Add the workflow file

Copy the workflow template below and add it to your repository at .github/workflows/evident.yml:

name: Evident AI Agent

on:
  workflow_dispatch:
    inputs:
      conversation_id:
        description: 'Conversation ID to process'
        required: true

concurrency:
  group: evident-${{ github.event.inputs.conversation_id }}
  cancel-in-progress: false

jobs:
  run-agent:
    runs-on: ubuntu-latest
    timeout-minutes: 60

    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Restore OpenCode session cache
        uses: actions/cache@v4
        with:
          path: .opencode
          key: evident-${{ github.event.inputs.conversation_id }}
          restore-keys: evident-

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Run Evident Agent
        run: npx --yes @evident-ai/cli@latest run --conversation "${{ github.event.inputs.conversation_id }}" --idle-timeout 30 --json
        env:
          EVIDENT_AGENT_KEY: ${{ secrets.EVIDENT_AGENT_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Save OpenCode session cache
        uses: actions/cache/save@v4
        if: always()
        with:
          path: .opencode
          key: evident-${{ github.event.inputs.conversation_id }}

      - name: Commit and push changes
        if: success()
        run: |
          git config user.name "Evident AI"
          git config user.email "ai@evident.run"
          git add -A
          git reset .opencode
          if ! git diff --staged --quiet; then
            git commit -m "feat: AI changes for conversation ${{ github.event.inputs.conversation_id }}"
            git push
          fi

Step 5: Add GitHub Secrets

In your repository, go to Settings → Secrets and variables → Actions and add two secrets:

  • EVIDENT_AGENT_KEY — The Agent API Key you generated in Step 3
  • ANTHROPIC_API_KEY — Your Anthropic API key (get one at console.anthropic.com)

Step 6: Send a test message

Go to your agent in the Evident web UI and send a message like "Hello — are you running?". You'll see the workflow trigger in GitHub Actions, and the response stream back in the web UI within 30–60 seconds.

How it works in detail

Message queuing

When you send a message to a GitHub Actions agent, Evident queues it rather than delivering it directly. The workflow is triggered with just a conversation_id — the CLI fetches the actual message content from the queue when it starts.

If you send multiple messages while the agent is running, they're queued and processed in order within the same workflow run. The runner exits after the queue is empty and a 30-second idle timeout passes.

Session persistence

OpenCode's session state (the .opencode/ folder) is cached between workflow runs using GitHub Actions cache, keyed by the conversation ID. This means multi-turn conversations work correctly — the agent remembers the context from previous messages.

Conversation locking

Only one workflow run can process a conversation at a time. If a workflow is already running for a conversation, new messages are queued and picked up by the running workflow. This prevents conflicts from concurrent runs.

Code changes

Any file changes the agent makes during a session are committed and pushed at the end of the workflow run. The commit is authored as Evident AI <ai@evident.run>.

Timeouts

  • Idle timeout (30 seconds) — How long the runner waits for new messages after the queue is empty before exiting. Configured with --idle-timeout 30 in the workflow template.
  • Job timeout (60 minutes) — The hard maximum for a single workflow run, configured with timeout-minutes: 60. Adjust this for tasks that take longer.

Troubleshooting

Runner not starting / workflow not triggered

  • Verify the workflow file exists at .github/workflows/evident.yml and has been pushed to the default branch
  • Check that the GitHub App is installed on your repository in Settings → GitHub
  • Ensure the EVIDENT_AGENT_KEY secret is set correctly in your repository secrets
  • Check the Actions tab in your GitHub repository for any workflow errors

Workflow fails immediately

  • Check the workflow run logs in GitHub Actions for the error message
  • Verify both EVIDENT_AGENT_KEY and ANTHROPIC_API_KEY are set as repository secrets (not environment secrets)
  • Make sure the workflow has contents: write permission if the agent needs to commit files

Conversation lock stuck

If a workflow crashed mid-run, the conversation may be locked. The lock expires automatically after ~60 minutes, or you can force-unlock it from the conversation view in the web UI.

Slow cold start

GitHub Actions runners have a cold start time of 10–60 seconds. This is normal — it's the time to provision the runner and install dependencies. Subsequent steps (including restoring the session cache) are fast.

Next steps