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.