onboard-repo · diff
git:20260914.7f3f3c0 to git:20261016.6dad935
14 added, 14 removed. Audit A to A.
---
name: onboard-repo
description: >-
Onboard a new GitHub repository to the ABCA platform so the agent can target it.
Use when the user says "onboard a repo", "add a repository", "register a repo",
"new repo", or gets a `REPO_NOT_ONBOARDED` / 422 error about an unregistered
repository.
---
# Repository Onboarding
You are helping an **operator** register a GitHub repository with their running ABCA
deployment so tasks can target it.
There are two paths.
**Prefer the CLI operator path (Path A)** when the repo can run on the
**platform/default-blueprint** setup — the default GitHub token secret, a model
already granted to the runtime, and the default egress allowlist. It's a single
runtime command against the deployed stack: no code change, no redeploy.
**Use the CDK Blueprint path (Path B)** when the repo needs its **own** config that
the CLI can't provision at runtime — a per-repo GitHub token, a model not yet
granted to the runtime, custom egress domains, Cedar HITL policies, or
system-prompt overrides. These are baked into infrastructure and require a redeploy
(with the correct permissions). When in doubt, start with Path A; if a task later
fails on a missing token / model grant / blocked egress, promote the repo to a
Blueprint.
> **This is an operation, not a contribution.** Onboarding a repo into your own
> deployment writes a record to the platform's RepoTable — it is **not** a change to
> the `aws-samples` codebase, so the ADR-003 contribution flow (GitHub issue →
> approval → feature branch) does **not** apply. Only invoke ADR-003 if the user is
> actually changing the platform source (e.g. wiring a brand-new Bedrock model into
> the stack — see "Model not yet wired into the runtime" below).
## Gather repository details
Use AskUserQuestion to collect (only the repository is required — the rest fall back to platform defaults):
- **Repository** — GitHub `owner/repo`. Must match exactly what's passed to `bgagent submit --repo` later.
- **Compute type** — `agentcore` (default) or `ecs`.
- - **Model** — default is the platform model (Opus 5). The geo prefix in the examples
+ - **Model** — default is the platform model (Opus 5.5). The geo prefix in the examples
below (`global.`) must match the deployment's `bedrockGeoRegion`; `bgagent repo
- onboard` rejects a mismatch at the CLI rather than letting the task fail at turn 0. If overriding, it must be a model **already granted to the runtime** (see "Model not yet wired into the runtime"), specified as a cross-Region **inference-profile ID** (e.g. `global.anthropic.claude-opus-5`), not a raw `anthropic.*` foundation-model ID.
+ onboard` rejects a mismatch at the CLI rather than letting the task fail at turn 0. If overriding, it must be a model **already granted to the runtime** (see "Model not yet wired into the runtime"), specified as a cross-Region **inference-profile ID** (e.g. `global.anthropic.claude-opus-5-5`), not a raw `anthropic.*` foundation-model ID.
- **Max turns** — default 100 (range 1–500).
- **Per-repo GitHub token** — only if this repo needs a different token than the platform default (provide its Secrets Manager ARN).
> **Per-task cost limits aren't set here.** `max_budget` / `max_turns` *per task* are flags on `bgagent submit` (the `submit-task` skill), not repo-onboarding fields. Onboarding sets only the per-repo **default** `max_turns`.
If the repo needs config the CLI can't provision (per-repo egress, Cedar policies, system-prompt overrides, or a not-yet-granted model), use **Path B** instead.
## Path A — CLI operator onboarding (default)
`bgagent repo onboard` writes (or re-activates) the repository's `RepoConfig` row in
the deployed RepoTable directly. It takes effect immediately — **no `agent.ts` edit,
no `cdk deploy`.**
```bash
bgagent repo onboard <owner/repo>
# common overrides:
- # --model <inference-profile-id> e.g. global.anthropic.claude-opus-5 (must be runtime-granted)
+ # --model <inference-profile-id> e.g. global.anthropic.claude-opus-5-5 (must be runtime-granted)
# --compute-type <agentcore|ecs>
# --max-turns <n> per-repo default turn limit
# --token-secret-arn <arn> per-repo GitHub token (else platform default)
# --runtime-arn <arn> override AgentCore runtime ARN (agentcore only)
# --poll-interval <ms> agent completion poll interval
```
Then confirm it landed:
```bash
bgagent repo list # status should be "active"
bgagent repo show <owner/repo> # full resolved config (secret ARNs redacted)
```
That's it — the repo is onboarded. Submit a task with the `submit-task` skill.
**Pick a model that is already wired into the runtime.** With no `--model`, the repo
uses the platform default — read it from the stack's `BedrockGeoRegion` +
`BedrockModelIds` outputs rather than a literal here. If you pass `--model`, use a cross-Region
- **inference profile ID** (e.g. `global.anthropic.claude-opus-5`), not a raw
+ **inference profile ID** (e.g. `global.anthropic.claude-opus-5-5`), not a raw
`anthropic.*` foundation-model ID. Only models the stack has granted the runtime can
be invoked — see "Model not yet wired into the runtime" before choosing a model the
deployment doesn't already support.
## Path B — CDK Blueprint (declarative / canonical)
Use this when the operator wants the repo committed to infrastructure-as-code (so a
fresh deploy re-creates it) rather than set as a runtime record. This **does** require
editing the stack and redeploying.
1. Read `cdk/src/stacks/agent.ts` to find where `Blueprint` constructs are defined and
the `repoTable` reference.
2. Add a construct following the existing pattern:
```typescript
new Blueprint(this, 'MyRepoBlueprint', {
repo: 'owner/repo',
repoTable: repoTable.table,
// Optional overrides:
// computeType: 'agentcore',
- // modelId: 'global.anthropic.claude-opus-5',
+ // modelId: 'global.anthropic.claude-opus-5-5',
// maxTurns: 100,
// maxBudgetUsd: 50,
// githubTokenSecretArn: 'arn:aws:secretsmanager:...',
});
```
3. Redeploy: `mise //cdk:compile` → `mise //cdk:diff` (show the diff) → `mise //cdk:deploy -- --require-approval never`.
> **Sample-repo shortcut:** the stack's AgentPlugins blueprint resolves its `repo` from
> `BLUEPRINT_REPO` (env) → CDK context `blueprintRepo` → default `awslabs/agent-plugins`.
> To target a fork of the sample without adding a construct, set
> `export BLUEPRINT_REPO=owner/repo` (or `cdk.json` context) and redeploy.
## Model not yet wired into the runtime (the one real code change)
A repo can only use a model the **runtime IAM role has `grantInvoke` for**. The granted
set is `DEFAULT_BEDROCK_MODEL_IDS` in
- `cdk/src/handlers/shared/bedrock-model-constants.ts` — Sonnet 4.6,
- Opus 4.8, Opus 5, and Haiku 4.5 — and a deployed stack publishes it as the
+ `cdk/src/handlers/shared/bedrock-model-constants.ts` — Opus 5.5 and Haiku 5.5 (the
+ defaults) plus Sonnet 4.6, Opus 4.8, Opus 5, and Haiku 4.5 — and a deployed stack publishes it as the
`BedrockModelIds` output, so read that rather than trusting this list to stay current:
```bash
aws cloudformation describe-stacks --stack-name <stack> \
--query "Stacks[0].Outputs[?OutputKey=='BedrockModelIds'].OutputValue" --output text
```
Onboarding a repo pinned to any **other** model fails at invoke with a 403 — the CLI
onboard succeeds, but tasks can't run. `bgagent repo onboard --model` checks the value
against that output and rejects an ungranted model up front.
Pin the **geo-prefixed inference-profile** form, matching the stack's `BedrockGeoRegion`
output (e.g. `global.anthropic.claude-opus-4-8`), not the bare id — Bedrock refuses bare
ids for on-demand invocation, and the IAM grant is scoped to one geography's profile ARNs.
Granting a **new** model is a deploy-time change, not a construct edit: the list is overridable via CDK context, either on the command line or in `cdk.json`. Both forms behave identically — the resolver JSON-parses the string `-c` delivers.
```bash
- cdk deploy -c bedrockModels='["anthropic.claude-opus-5","anthropic.claude-haiku-4-5-20251001-v1:0","anthropic.claude-sonnet-4-6"]'
+ cdk deploy -c bedrockModels='["anthropic.claude-opus-5-5","anthropic.claude-haiku-5-5","anthropic.claude-sonnet-4-6"]'
```
- The override **REPLACES** the default list rather than adding to it, so it must include the two models the stack injects as `ANTHROPIC_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL` — Opus 5 and Haiku 4.5. Omitting either fails at synth, naming the missing model, because every substrate is told to invoke them regardless of this list. (`--context-file` does not work for this: it is accepted and silently ignored.)
+ The override **REPLACES** the default list rather than adding to it, so it must include the two models the stack injects as `ANTHROPIC_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL` — Opus 5.5 and Haiku 5.5. Omitting either fails at synth, naming the missing model, because every substrate is told to invoke them regardless of this list. (`--context-file` does not work for this: it is accepted and silently ignored.)
For a persistent setting, put the same array in the `context` block of `cdk.json`:
```jsonc
// cdk.json — this REPLACES the default list, so include the platform defaults
- // (Opus 5 + Haiku 4.5) or the stack's own defaults are ungranted
+ // (Opus 5.5 + Haiku 5.5) or the stack's own defaults are ungranted
"context": {
"bedrockModels": [
- "anthropic.claude-opus-5",
- "anthropic.claude-haiku-4-5-20251001-v1:0",
+ "anthropic.claude-opus-5-5",
+ "anthropic.claude-haiku-5-5",
"anthropic.claude-sonnet-4-6"
]
}
```
Three constraints on the value. Entries are **bare** ids — the geo prefix is derived from
`bedrockGeoRegion`, and a prefixed entry is rejected. Patterns are rejected too: these ids
become the resource half of the IAM grant, so a `*` would grant every inference profile in
the account. And each entry must have a live cross-Region inference profile:
```bash
aws bedrock get-inference-profile --inference-profile-identifier <geo>.<model>
```
A granted model with **no** profile is the trap — it passes the CLI's `--model` check and
workflow admission (both read the grant list) and only fails at turn 0.
`bgagent platform doctor` checks the whole granted set for exactly this and names any
model that does not resolve.
**Account-level Bedrock model access** is separate from IAM: the account must have the
model enabled for the Region — complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)
prerequisites (Marketplace actions / Anthropic first-time use where applicable). For
cross-Region profiles, IAM and SCPs must allow Bedrock in source **and** destination
Regions.
If the user just wants the agent working now, leave `model_id` unset so the repo takes the
platform default, and treat "add model X" as a separate, later change.
## Per-repository configuration reference
| Setting | Purpose | Default |
|---------|---------|---------|
| `compute_type` | Execution strategy | `agentcore` |
| `runtime_arn` | AgentCore runtime override | Platform default |
- | `model_id` | AI model for tasks (inference profile ID) | Platform default (Opus 5, as `<BedrockGeoRegion>.anthropic.claude-opus-5`) |
+ | `model_id` | AI model for tasks (inference profile ID) | Platform default (Opus 5.5, as `<BedrockGeoRegion>.anthropic.claude-opus-5-5`) |
| `max_turns` | Turn limit per task | 100 |
| `max_budget_usd` | Cost ceiling per task | Unlimited |
| `system_prompt_overrides` | Custom system instructions | None |
| `github_token_secret_arn` | Repo-specific GitHub token | Platform default |
| `poll_interval_ms` | Completion polling frequency | 30000ms |
Task-level parameters override per-repo defaults; if neither specifies a value, platform defaults apply.
## Common issues
- **`REPO_NOT_ONBOARDED` / 422** — the repo isn't registered. Run `bgagent repo onboard <owner/repo>` (Path A). Confirm the `owner/repo` matches exactly what you pass to `bgagent submit --repo`.
- **Preflight failure after onboarding** — the GitHub PAT lacks access to the new repo. Ensure the token has Contents (read/write) + Pull requests (read/write) on it, or onboard with a repo-specific `--token-secret-arn`.
- - **400 "Invocation with on-demand throughput isn't supported"** — `model_id` is a raw foundation-model ID; use the inference-profile ID (e.g. `global.anthropic.claude-opus-5`).
+ - **400 "Invocation with on-demand throughput isn't supported"** — `model_id` is a raw foundation-model ID; use the inference-profile ID (e.g. `global.anthropic.claude-opus-5-5`).
- **403 "not authorized to perform bedrock:InvokeModelWithResponseStream"** — the repo's model isn't wired into the runtime. See "Model not yet wired into the runtime."
- **Model not available / "not available on your Bedrock deployment"** — account-level Bedrock access isn't enabled for that model/Region (separate from IAM); complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html), then use an enabled inference-profile ID.