Настройка

Внешний кодовый агент

Как подключить исполнителя, который работает в GitHub Actions и открывает pull request — workflow, секреты, список репозиториев, токен, манифест, запуск, одобрение и типовые отказы.

Внешний кодовый агент на живом репозитории не проверялся: сценарий собран по коду и тестам версии 0.9.2, но целиком, от сообщения до PR, его никто не прогонял. Работа агента через шлюз колыбели (Anthropic-совместимый /v1/messages, ANTHROPIC_BASE_URL) не подтверждена: в примере ниже агент ходит в Anthropic по собственному ANTHROPIC_API_KEY. Первые запуски делайте на тестовом репозитории.

Лид команды поручает задачу исполнителю с внешним исполнением. Колыбель не вызывает для него модель, а после вашего одобрения запускает в репозитории GitHub Actions workflow; агент работает в ветке cradle/<id задачи> и открывает pull request, колыбель проверяет его по CI. Сливает PR только человек.

1. Положите workflow в репозиторий

Файл .github/workflows/cradle-task.yml (имя фиксировано: колыбель запускает именно его через workflow_dispatch с входами task_id, prompt и base_branch). Рабочая часть образца:

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

Название запуска (run-name) содержит id задачи — по нему колыбель находит запуск. Последний шаг коммитит правки, которые действие оставило в рабочем дереве; если ветка не отличается от базовой, шаг падает с текстом «агент не внёс изменений», и PR не открывается.

Как проверить. Вкладка Actions репозитория показывает workflow «Cradle task» с кнопкой «Run workflow».

Если нет. Workflow не виден — файл не в базовой ветке или путь другой.

2. Секреты репозитория и права токенов

В настройках репозитория (Secrets → Actions) задайте:

  • CRADLE_GITHUB_TOKEN — токен GitHub App или PAT с правом создавать ветки и PR (contents: write, pull-requests: write), без права слияния. Не GITHUB_TOKEN: коммиты и PR, сделанные им, не запускают CI.
  • ANTHROPIC_API_KEY — ключ для агента.

Защиту базовой ветки (обязательное ревью, запрет прямого push) включите на стороне GitHub.

Не давайте токенам право менять файлы workflow (workflows у PAT, Workflows у GitHub App): иначе агент сможет ослабить проверки CI в своём PR.

Отдельный токен понадобится колыбели (шаг 4): она вызывает GitHub API — POST /repos/<репозиторий>/actions/workflows/cradle-task.yml/dispatches, а также читает запуски workflow, pull request'ы (/pulls) и проверки коммита (/commits/<sha>/check-runs, /commits/<sha>/status). Выдайте ему права, достаточные для этих вызовов, и никаких лишних.

3. Создайте команду с внешним исполнителем

Исполнитель описывается полем execution манифеста cradle.team/v1 (Манифест команды); модель для него не вызывается, репозиторий и базовая ветка заданы в самом поле. Сохраните манифест, подставив свой репозиторий:

{
  "schema": "cradle.team/v1",
  "name": "code-team",
  "title": "Команда разработки",
  "captain": {
    "id": "dispatcher",
    "title": "Диспетчер",
    "prompt": "Ты — диспетчер команды разработки. Принимаешь входящую задачу и передаёшь её лиду tech-lead. Код не пишешь.",
    "requirement": "general"
  },
  "checker": {
    "id": "checker",
    "title": "Проверяющий",
    "prompt": "Ты — проверяющий. Сверяешь pull request исполнителя с постановкой и результатом CI. Ничего не сливаешь: PR сливает человек.",
    "requirement": "general",
    "onReject": "return-to-lead"
  },
  "leads": [
    {
      "id": "tech-lead",
      "title": "Техлид",
      "prompt": "Ты — техлид. Формулируешь задачу как чёткое поручение (контекст, что сделать, критерии приёмки, чего не трогать) и передаёшь внешнему исполнителю code-agent. Merge и push в основную ветку запрещены: PR сливает только человек.",
      "requirement": "reasoning",
      "sources": ["api"],
      "members": [
        {
          "id": "code-agent",
          "title": "Кодовый агент",
          "prompt": "Внешний кодовый агент (Claude Code в GitHub Actions). Работает в ветке cradle/<задача> и открывает pull request.",
          "category": "coding",
          "execution": {
            "kind": "external",
            "repository": "your-org/your-repo",
            "baseBranch": "main"
          }
        }
      ]
    }
  ]
}

Лид принимает сообщения только из HTTP API ("sources": ["api"]). Импортируйте манифест на странице любой команды: Импорт → вставьте JSON → Проверить → Создать команду (Команда). Для лида и Checker нужны модели (Ключи и модели); если лид и Checker работают на облачных моделях, переключите контур: cradle teams update code-team --contour cloud.

Как проверить. План показывает "valid":true; в ответе есть предупреждение repository_not_allowed — это нормально до шага 4; после создания на канвасе команды четыре агента, у «Кодовый агент» репозиторий.

Если нет. missing.models блокирует применение — зарегистрируйте недостающие модели; ошибка с путём JSON Pointer — поправьте поле.

4. Разрешите репозиторий и задайте токен

Это действия администратора организации (скоуп org:admin: ключ admin:* или человек с ролью owner или admin); ни экрана в консоли, ни команды CLI для них нет, поэтому даны вызовы POST /api/v1/rpc/teams:setCodeRepositories и POST /api/v1/rpc/teams:setCodeToken. В манифест ни список, ни токен не входят. Команда должна уже существовать.

Разрешённые репозитории команды: аргументы — slug команды и список 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"]]}'

Токен GitHub команды; null вместо токена удаляет его:

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>"]}'

Токен (8–500 символов) хранится зашифрованным и нигде не возвращается; на команду одна запись, повторный вызов заменяет её. Вместо slug можно передать null: общий токен колыбели, его задаёт только оператор с доступом ко всем командам.

Как проверить. Ответы {"result":{"ok":true,"slug":"code-team","repositories":["your-org/your-repo"]}} и {"result":{"ok":true,"hasToken":true}}.

Если нет. the cradle cannot encrypt secrets on this host: the token is not stored — у сервера нет ключа шифрования (CRADLE_SECRET_KEY или записываемый каталог данных для secret.key); invalid input: … — токен короче 8 символов или slug неверного вида.

5. Запустите задачу и одобрите её

Отправьте команде сообщение через HTTP API ключом этой команды (Каналы):

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"}'

Если лид выбрал поручить задачу исполнителю code-agent, в «Ждут решения» появляется тикет с причиной tool_approval: колыбель просит разрешить запуск code.dispatch. Каждый запуск ждёт человека. Одобрите его (Ждут решения, раздел «Одобрение вызова инструмента»); отклонение завершает задачу ошибкой.

Как проверить. После одобрения в разговоре (страница Разговоры) — сообщение «Задача отправлена исполнителю «Кодовый агент». Когда он откроет PR, я напишу.»; в Actions репозитория идёт запуск cradle task <id задачи>; ответы бота по этому чату можно забрать вызовом GET /api/v1/messages/task-1.

Если нет. Тикета нет — лид ответил сам или позвал человека (посмотрите причину удержания); сообщение «Не получилось: …» — причина из таблицы ниже.

6. Что происходит дальше и что видно

Колыбель раз в 2 минуты ищет PR из ветки cradle/<id задачи>:

Что в разговореЧто произошло
Исполнитель открыл PR: <ссылка>. Идёт проверка.PR найден, задача in_review
PR прошёл проверки: <ссылка>. Слияние — за человеком.PR из cradle/<id> в базовую ветку разрешённого репозитория не слит, а все проверки завершены успешно (success, neutral, skipped): задача done
«CI в PR красный (…). Жду решения оператора: вернуть задачу исполнителю.»первая красная проверка: в «Ждут решения» тикет tool_approval — одобрение запускает агента снова в той же ветке
«Задача возвращена исполнителю …»возврат одобрен
«Не получилось: …»задача failed

Если после возвращения проверки снова красные, задача failed, а оператору приходит тикет task_ci_failed со ссылкой на PR и перечнем упавших проверок.

Сроки (поля settings.codeRunner в app-state.json каталога данных): опрос pollMinutes — 2 минуты; ожидание PR после отправки timeoutMinutes — 60; ожидание незавершённых проверок checksTimeoutMinutes — 60. Если у PR за 10 минут нет ни одной проверки, задача failed («нет CI»).

7. Типовые отказы

Причину колыбель пишет в разговор строкой «Не получилось: …»:

СообщениеПричинаЧто делать
repository <репо> is not in the code repositories of team <slug>: an organization admin must allow it (teams:setCodeRepositories)репозиторий не разрешён командешаг 4
no GitHub token: add a "github" key to the provider credentials of the team …у команды нет токенаteams:setCodeToken, шаг 4
agent "<имя>" is not an external executorу агента нет executionшаг 3
GitHub refused workflow_dispatch of cradle-task.yml in <репо>: HTTP <код> …нет файла workflow в базовой ветке, самой ветки или прав у токенашаги 1–2
запуск workflow завершился с результатом «failure», PR нет: <ссылка>запуск workflow упалоткройте ссылку на запуск и разберите его журнал
запуск workflow не найден и PR нет за N мин после отправки или PR не появился за N мин после отправкиworkflow не стартовал или не открыл PRжурнал Actions, шаг 1
в репозитории нет CI: за 10 мин у PR не появилось ни одной проверкив репозитории нет проверок для PRнастроить CI
проверки PR красные и после возвращения: …CI красный дваждыразобрать PR вручную