Onboard Repo

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 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.
• 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.

bgagent repo onboard <owner/repo>
# common overrides:
#   --model <inference-profile-id>     e.g. global.anthropic.claude-opus-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:

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 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:

   new Blueprint(this, 'MyRepoBlueprint', {
     repo: 'owner/repo',
     repoTable: repoTable.table,
     // Optional overrides:
     // computeType: 'agentcore',
     // modelId: 'global.anthropic.claude-opus-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 BedrockModelIds output, so read that rather than trusting this list to stay current:

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.

cdk deploy -c bedrockModels='["anthropic.claude-opus-5","anthropic.claude-haiku-4-5-20251001-v1:0","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.)

For a persistent setting, put the same array in the context block of cdk.json:

// 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
"context": {
  "bedrockModels": [
    "anthropic.claude-opus-5",
    "anthropic.claude-haiku-4-5-20251001-v1:0",
    "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:

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 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

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).
• 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, then use an enabled inference-profile ID.