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}."
fiThe 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. NotGITHUB_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 conversation | What 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):
| Message | Cause | What 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 team | step 4 |
no GitHub token: add a "github" key to the provider credentials of the team … | the team has no token | teams:setCodeToken, step 4 |
agent "<name>" is not an external executor | the agent has no execution | step 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 rights | steps 1–2 |
запуск workflow завершился с результатом «failure», PR нет: <ссылка> (the workflow run ended with the result "failure", no PR) | the workflow run failed | open 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 PR | the 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 PR | set up CI |
проверки PR красные и после возвращения: … (the PR checks are red even after the return) | CI is red twice | go through the PR by hand |
Waiting for decision
What happens to a message that waits for a human, hold reasons, approving a reply and approving a tool call.
Architecture overview
How Cradle is built as a host-independent core with one entry point — the headless cradle-server and the web console — and how a message travels from start to finish.