GitHub Actions

Run buildd tasks automatically on GitHub Actions. When a task is created, buildd dispatches a repository_dispatch event to your repo, triggering a workflow that uses claude-code-action@v1 with the buildd MCP server.

Prerequisites

Buildd GitHub App installed and connected to your repo (see GitHub integration for setup)
Workspace linked to a GitHub repository
Anthropic API key for claude-code-action
Buildd API key for the MCP server (create one from the dashboard)

Quick Setup

Add this workflow file to your repository at .github/workflows/buildd-worker.yml:

name: Buildd Worker
on:
  repository_dispatch:
    types: [buildd-task]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  run-task:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            You are a buildd CI worker. Use the buildd MCP tools to:
            1. Claim a pending task (the dispatched task_id is: ${{ github.event.client_payload.task_id }})
            2. Read the task details and do the work
            3. Commit and push your changes
            4. Create a PR via buildd MCP (create_pr action)
            5. Mark the task complete (complete_task action)

            Workspace: ${{ github.event.client_payload.workspace_id }}
          claude_args: |
            --mcp-config '{"mcpServers":{"buildd":{"type":"http","url":"https://buildd.dev/api/mcp","headers":{"Authorization":"Bearer ${{ secrets.BUILDD_API_KEY }}"}}}}'
            --allowedTools mcp__buildd__buildd,mcp__buildd__recall,mcp__buildd__learn,mcp__buildd__check_path_claim,Bash,Read,Write,Edit,Glob,Grep

--allowedTools is an allowlist: a buildd tool you do not name here cannot be called, and the agent gets no error explaining why — the tool simply is not there. The current knowledge tools are recall and learn, so both must be listed. Earlier versions of this page listed only the legacy mcp__buildd__buildd_memory, which left CI agents unable to read or write team memory at all.

mcp__buildd__buildd_memory is still callable and is the only MCP path with working type / files read filters, so add it too if you rely on those. Otherwise leave it out — recall and learn cover the same ground.

mcp__buildd__check_path_claim and mcp__buildd__send_worker_message are registered only for worker- and admin-level keys. Listing a tool the server does not register is harmless, so the line above is safe either way.

How It Works

Task created in buildd (dashboard, API, or GitHub issue with buildd label)
Buildd sends a repository_dispatch event to the linked GitHub repo
GitHub Actions triggers the workflow
claude-code-action runs with the buildd MCP server connected
Agent claims the task, does the work, creates a PR, and reports completion
Task status updates in real-time on the buildd dashboard

Secrets Setup

Add these secrets in your repository under Settings > Secrets and variables > Actions:

Secret	Description
`ANTHROPIC_API_KEY`	Your Anthropic API key for Claude
`BUILDD_API_KEY`	Your buildd API key (`bld_xxx`) from the dashboard

Multi-Agent Workflows

Run multiple agents in parallel using a matrix strategy. Each agent independently claims and works on a pending task from the workspace:

jobs:
  run-task:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        agent: [1, 2, 3]
      max-parallel: 3
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            You are buildd CI worker #${{ matrix.agent }}. Use the buildd MCP tools to:
            1. Claim a pending task from the workspace
            2. Do the work, commit, push, create PR
            3. Mark the task complete
          claude_args: |
            --mcp-config '{"mcpServers":{"buildd":{"type":"http","url":"https://buildd.dev/api/mcp","headers":{"Authorization":"Bearer ${{ secrets.BUILDD_API_KEY }}"}}}}'
            --allowedTools mcp__buildd__buildd,mcp__buildd__recall,mcp__buildd__learn,mcp__buildd__check_path_claim,Bash,Read,Write,Edit,Glob,Grep

Dispatch Triggers

The repository_dispatch event fires automatically when:

A task is created via the dashboard
A GitHub issue with the buildd or ai label is opened
A task is created via the API
A scheduled task fires

The dispatch only fires if no local runner or webhook handler claims the task first. It serves as the fallback in the dispatch chain.

Customization

Limiting agent iterations

Add --max-turns to claude_args to cap how many tool-call rounds the agent can take:

claude_args: |
  --max-turns 20
  --mcp-config '{"mcpServers":{"buildd":{"type":"http","url":"https://buildd.dev/api/mcp","headers":{"Authorization":"Bearer ${{ secrets.BUILDD_API_KEY }}"}}}}'
  --allowedTools mcp__buildd__buildd,mcp__buildd__recall,mcp__buildd__learn,mcp__buildd__check_path_claim,Bash,Read,Write,Edit,Glob,Grep

Choosing a model

Pass --model to select a specific Claude model:

claude_args: |
  --model claude-opus-5
  --mcp-config '{"mcpServers":{"buildd":{"type":"http","url":"https://buildd.dev/api/mcp","headers":{"Authorization":"Bearer ${{ secrets.BUILDD_API_KEY }}"}}}}'
  --allowedTools mcp__buildd__buildd,mcp__buildd__recall,mcp__buildd__learn,mcp__buildd__check_path_claim,Bash,Read,Write,Edit,Glob,Grep

Team memory

recall reads the team knowledge base and learn writes to it — lessons persist across tasks, machines and sessions. Both are separate MCP tools, so both must appear in --allowedTools; the workflows above include them.

A good CI prompt tells the agent to call recall with the task title before starting and learn on any non-obvious discovery. See Memory for what is worth saving.

Adding CI steps

You can add linting, testing, or other CI steps before or after the agent runs:

steps:
  - uses: actions/checkout@v4

  - name: Install dependencies
    run: npm ci

  - name: Run linter
    run: npm run lint

  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
      prompt: |
        You are a buildd CI worker. Use the buildd MCP tools to claim and complete the task.
        The project dependencies are already installed and linting has passed.
      claude_args: |
        --mcp-config '{"mcpServers":{"buildd":{"type":"http","url":"https://buildd.dev/api/mcp","headers":{"Authorization":"Bearer ${{ secrets.BUILDD_API_KEY }}"}}}}'
        --allowedTools mcp__buildd__buildd,mcp__buildd__recall,mcp__buildd__learn,mcp__buildd__check_path_claim,Bash,Read,Write,Edit,Glob,Grep

GitHub Actions

On this page