Setup

External code agent

How to connect an executor that works in GitHub Actions and opens a pull request — the workflow, secrets, the list of repositories, the token, the manifest, running, approval and typical failures.

The external code agent has not been tried on a live repository: the scenario is assembled from the code and tests of version 0.9.2, but nobody has run it end to end, from the message to the PR. Running the agent through the cradle's gateway (the Anthropic-compatible /v1/messages, ANTHROPIC_BASE_URL) is not confirmed: in the example below the agent calls Anthropic with its own ANTHROPIC_API_KEY. Make the first runs on a test repository.

A team's lead hands a task to an executor with external execution. The cradle does not call a model for it; after your approval it starts a GitHub Actions workflow in the repository; the agent works in the branch cradle/<task id> and opens a pull request, and the cradle checks it against CI. Only a human merges the PR.

1. Put the workflow into the repository

The file .github/workflows/cradle-task.yml (the name is fixed: the cradle starts exactly this one through workflow_dispatch with the inputs task_id, prompt and base_branch). The working part of the sample:

name: Cradle task
# Cradle finds the run by the task id in its title.
run-name: cradle task ${{ inputs.task_id }}

on:
  workflow_dispatch:
    inputs:
      task_id:
        description: Cradle task id; the branch is cradle/<task_id>
        required: true
        type: string
      prompt:
        description: What the agent has to do
        required: true
        type: string
      base_branch:
        description: Branch the pull request goes into
        required: true
        type: string
        default: main

permissions:
  contents: write
  pull-requests: write

jobs:
  agent:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      TASK_ID: ${{ inputs.task_id }}
      BASE_BRANCH: ${{ inputs.base_branch }}
      GH_TOKEN: ${{ secrets.CRADLE_GITHUB_TOKEN }}
    steps:
      - name: Check out the base branch
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.base_branch }}
          fetch-depth: 0
          token: ${{ secrets.CRADLE_GITHUB_TOKEN }}

      - name: Create the branch cradle/<task_id>, or carry on in it
        run: |
          git config user.name "cradle-agent"
          git config user.email "cradle-agent@users.noreply.github.com"
          if git ls-remote --exit-code --heads origin "cradle/${TASK_ID}" > /dev/null; then
            # Cradle sent the task back (failed checks): work in the branch of the open pull request, do not start a new one.
            git fetch origin "cradle/${TASK_ID}"
            git switch -C "cradle/${TASK_ID}" "origin/cradle/${TASK_ID}"
          else
            git switch -c "cradle/${TASK_ID}"
          fi
          echo "START_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"

      - name: Run the agent
        uses: anthropics/claude-code-action@v1
        with:
          prompt: ${{ inputs.prompt }}
          github_token: ${{ secrets.CRADLE_GITHUB_TOKEN }}
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: --max-turns 30

      - name: Commit what is left, push the branch and open the pull request
        run: |
          # The action may leave its edits uncommitted: commit them, if there are any.
          git add -A
          if ! git diff --cached --quiet; then
            git commit -m "Cradle task ${TASK_ID}"
          fi
          # The branch is where it was before the agent: there is nothing new to put into a pull request.
          if [ "$(git rev-parse HEAD)" = "${START_SHA}" ]; then
            echo "::error::агент не внёс изменений: в ветке cradle/${TASK_ID} нет новых коммитов"
            exit 1
          fi
          git push origin "HEAD:refs/heads/cradle/${TASK_ID}"
          # A return pushes to the branch of the pull request that is already open.
          if [ "$(gh pr list --head "cradle/${TASK_ID}" --state open --json number --jq length)" = "0" ]; then
            gh pr create --head "cradle/${TASK_ID}" --base "${BASE_BRANCH}" \
              --title "Cradle task ${TASK_ID}" \
              --body "Opened by the external executor of Cradle for task ${TASK_ID}."
          fi

The run name (run-name) contains the task id — the cradle finds the run by it. The last step commits the edits the action left in the working tree; if the branch does not differ from the base one, the step fails with the text "агент не внёс изменений" (the agent made no changes), and no PR is opened.

How to check. The repository's Actions tab shows the workflow "Cradle task" with a "Run workflow" button.

If it did not work. The workflow is not visible — the file is not in the base branch or the path is different.

2. Repository secrets and token permissions

In the repository settings (Secrets → Actions) set:

  • CRADLE_GITHUB_TOKEN — a GitHub App or PAT token that may create branches and PRs (contents: write, pull-requests: write), without the right to merge. Not GITHUB_TOKEN: commits and PRs made with it do not start CI.
  • ANTHROPIC_API_KEY — the key for the agent.

Turn on protection of the base branch (required review, no direct push) on the GitHub side.

Do not give the tokens the right to change workflow files (workflows for a PAT, Workflows for a GitHub App): otherwise the agent can weaken the CI checks in its own PR.

The cradle needs a separate token (step 4): it calls the GitHub API — POST /repos/<repository>/actions/workflows/cradle-task.yml/dispatches, and also reads workflow runs, pull requests (/pulls) and commit checks (/commits/<sha>/check-runs, /commits/<sha>/status). Give it the permissions that are enough for these calls and nothing extra.

3. Create a team with an external executor

The executor is described by the execution field of the cradle.team/v1 manifest (Team manifest); no model is called for it, and the repository and the base branch are set in the field itself. Save the manifest, putting in your own repository:

{
  "schema": "cradle.team/v1",
  "name": "code-team",
  "title": "Development team",
  "captain": {
    "id": "dispatcher",
    "title": "Dispatcher",
    "prompt": "You are the dispatcher of the development team. You take an incoming task and hand it to the lead tech-lead. You do not write code.",
    "requirement": "general"
  },
  "checker": {
    "id": "checker",
    "title": "Checker",
    "prompt": "You are the checker. You compare the executor's pull request with the task and the CI result. You merge nothing: a human merges the PR.",
    "requirement": "general",
    "onReject": "return-to-lead"
  },
  "leads": [
    {
      "id": "tech-lead",
      "title": "Tech lead",
      "prompt": "You are the tech lead. You formulate the task as a clear assignment (context, what to do, acceptance criteria, what not to touch) and hand it to the external executor code-agent. Merge and push to the main branch are forbidden: only a human merges the PR.",
      "requirement": "reasoning",
      "sources": [
        "api"
      ],
      "members": [
        {
          "id": "code-agent",
          "title": "Code agent",
          "prompt": "An external code agent (Claude Code in GitHub Actions). It works in the branch cradle/<task> and opens a pull request.",
          "category": "coding",
          "execution": {
            "kind": "external",
            "repository": "your-org/your-repo",
            "baseBranch": "main"
          }
        }
      ]
    }
  ]
}

The lead accepts messages only from the HTTP API ("sources": ["api"]). Import the manifest on the page of any team: Import → paste the JSON → Check → Create team (Team). The lead and the Checker need models (Keys and models); if the lead and the Checker run on cloud models, switch the contour: cradle teams update code-team --contour cloud.

How to check. The plan shows "valid":true; the answer has the warning repository_not_allowed — that is normal until step 4; after creation the team's canvas shows four agents, and the "Code agent" has the repository.

If it did not work. missing.models blocks applying — register the missing models; an error with a JSON Pointer path — fix that field.

4. Allow the repository and set the token

These are actions of an organization administrator (the scope org:admin: an admin:* key or a person with the role owner or admin); there is neither a console screen nor a CLI command for them, so the calls POST /api/v1/rpc/teams:setCodeRepositories and POST /api/v1/rpc/teams:setCodeToken are given. Neither the list nor the token is part of the manifest. The team has to exist already.

The team's allowed repositories: the arguments are the team slug and a list of owner/name.

curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/teams:setCodeRepositories \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"args":["code-team",["your-org/your-repo"]]}'

The team's GitHub token; null instead of a token removes it:

curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/teams:setCodeToken \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"args":["code-team","<github-token>"]}'

The token (8–500 characters) is stored encrypted and is never returned; there is one entry per team, a repeated call replaces it. Instead of a slug you can pass null: the cradle's shared token, which only an operator with access to all teams sets.

How to check. The answers are {"result":{"ok":true,"slug":"code-team","repositories":["your-org/your-repo"]}} and {"result":{"ok":true,"hasToken":true}}.

If it did not work. the cradle cannot encrypt secrets on this host: the token is not stored — the server has no encryption key (CRADLE_SECRET_KEY or a writable data directory for secret.key); invalid input: … — the token is shorter than 8 characters or the slug is of the wrong form.

5. Start a task and approve it

Send the team a message through the HTTP API with a key of this team (Channels):

curl -sS -X POST http://127.0.0.1:31416/api/v1/messages \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Add an Installation section to the README","chatId":"task-1","mode":"async"}'

If the lead chose to hand the task to the executor code-agent, a ticket with the reason tool_approval appears in "Waiting for decision": the cradle asks to allow the code.dispatch run. Every run waits for a human. Approve it (Waiting for decision, the section "Approving a tool call"); rejection ends the task with an error.

How to check. After the approval the conversation (the Conversations page) has the message Задача отправлена исполнителю «Code agent». Когда он откроет PR, я напишу. (the task was sent to the executor; I will write when it opens a PR); a run cradle task <task id> is going in the repository's Actions; the bot's replies in that chat can be collected with GET /api/v1/messages/task-1.

If it did not work. No ticket — the lead answered itself or called a human (look at the hold reason); the message Не получилось: … (it did not work) — the reason is in the table below.

6. What happens next and what you see

Every 2 minutes the cradle looks for a PR from the branch cradle/<task id>:

What is in the conversationWhat happened
Исполнитель открыл PR: <ссылка>. Идёт проверка. (the executor opened a PR; checking)the PR is found, the task is in_review
PR прошёл проверки: <ссылка>. Слияние — за человеком. (the PR passed the checks; merging is up to a human)the PR from cradle/<id> into the base branch of an allowed repository is not merged, and all checks finished successfully (success, neutral, skipped): the task is done
CI в PR красный (…). Жду решения оператора: вернуть задачу исполнителю. (CI in the PR is red; waiting for the operator to return the task to the executor)the first red check: a tool_approval ticket in "Waiting for decision" — approval starts the agent again in the same branch
Задача возвращена исполнителю … (the task was returned to the executor)the return was approved
Не получилось: … (it did not work)the task is failed

If after the return the checks are red again, the task is failed, and the operator gets a task_ci_failed ticket with a link to the PR and the list of failed checks.

Timings (the settings.codeRunner fields in app-state.json of the data directory): the poll pollMinutes is 2 minutes; waiting for a PR after sending timeoutMinutes is 60; waiting for unfinished checks checksTimeoutMinutes is 60. If a PR has no check at all after 10 minutes, the task is failed ("no CI").

7. Typical failures

The cradle writes the reason into the conversation as a line Не получилось: … (it did not work):

MessageCauseWhat to do
repository <repo> is not in the code repositories of team <slug>: an organization admin must allow it (teams:setCodeRepositories)the repository is not allowed for the teamstep 4
no GitHub token: add a "github" key to the provider credentials of the team …the team has no tokenteams:setCodeToken, step 4
agent "<name>" is not an external executorthe agent has no executionstep 3
GitHub refused workflow_dispatch of cradle-task.yml in <repo>: HTTP <code> …no workflow file in the base branch, no such branch, or the token lacks rightssteps 1–2
запуск workflow завершился с результатом «failure», PR нет: <ссылка> (the workflow run ended with the result "failure", no PR)the workflow run failedopen the run link and read its log
запуск workflow не найден и PR нет за N мин после отправки (the run was not found and there is no PR N min after sending) or PR не появился за N мин после отправки (the PR did not appear N min after sending)the workflow did not start or did not open a PRthe Actions log, step 1
в репозитории нет CI: за 10 мин у PR не появилось ни одной проверки (no CI in the repository: the PR got no check in 10 min)the repository has no checks for a PRset up CI
проверки PR красные и после возвращения: … (the PR checks are red even after the return)CI is red twicego through the PR by hand