Skip to content

fix(jira): jira map accepts repos with no Blueprint → every trigger 422 REPO_NOT_ONBOARDED #369

@mayakost

Description

@mayakost

Summary

bgagent jira map <cloud-id> <PROJECT-KEY> --repo owner/repo accepts and persists a project→repo mapping for a repo that has no active Blueprint in the RepoTable. Every subsequent label trigger then fails at task-creation time with 422 REPO_NOT_ONBOARDED, and — because the failure-feedback comment also fails (see companion issue) — the operator sees nothing happen at all. There is no signal at map time that the repo will never work.

Reproduction

  1. bgagent jira setup (succeeds).
  2. bgagent jira map <cloud-id> TEST --repo owner/repo-without-blueprint → reports success, writes an active row to JiraProjectMappingTable.
  3. Add the trigger label to an issue in TEST.
  4. Webhook verifies, label trigger fires, processor calls createTaskCore, which returns:
    422 REPO_NOT_ONBOARDED: Repository 'owner/repo-without-blueprint' is not onboarded. Register it with a Blueprint before submitting tasks.
  5. No task created; no visible feedback.

Root cause / context

  • The onboarding gate is in cdk/src/handlers/shared/create-task-core.ts:163-167 via lookupRepo (cdk/src/handlers/shared/repo-config.ts:116): a repo is "onboarded" only if it has a RepoTable row with status = 'active'.
  • Repos are onboarded exclusively by instantiating a Blueprint construct (cdk/src/constructs/blueprint.ts) in the stack and deploying (cdk/src/stacks/agent.ts:154). There is no runtime/CLI onboarding path.
  • bgagent jira map does no validation that the target repo is onboarded, so the misconfiguration is only discovered at trigger time, deep in the processor, where the error is nearly invisible.

Proposed fix (open to alternatives)

  1. Validate at map time: have bgagent jira map (and the Linear equivalent) check the repo is onboarded (active in RepoTable) before writing the mapping, and fail loudly with guidance if not. Requires a lookup path the CLI can call (API endpoint or direct table read with appropriate IAM).
  2. Document the prerequisite prominently in docs/guides/JIRA_SETUP_GUIDE.md: a repo must have a deployed Blueprint before it can be mapped, with the exact steps.
  3. Optionally, make the processor's REPO_NOT_ONBOARDED path emit a clearer operator-facing signal (depends on companion feedback-comment fix).

Acceptance criteria

  • bgagent jira map rejects (or clearly warns about) a repo that is not onboarded, with actionable guidance, instead of silently persisting a mapping that can never trigger.
  • docs/guides/JIRA_SETUP_GUIDE.md (and the Linear guide if applicable) state the Blueprint-onboarding prerequisite and link to the Blueprint/onboarding steps. Starlight mirrors regenerated (cd docs && node scripts/sync-starlight.mjs).
  • Tests cover the validation path in cli/.
  • Decide & document whether Linear's link/map flow needs the same guard (it shares the same onboarding gate via create-task-core).

Notes

Gate: create-task-core.ts:163. Lookup semantics: repo-config.ts:108-148. Blueprint construct: constructs/blueprint.ts; stack wiring + BLUEPRINT_REPO/blueprintRepo context at stacks/agent.ts:153.

Metadata

Metadata

Assignees

No one assigned

    Labels

    adaptersThird-party integrations: Linear, Slack, GitHub App, notification/deploy providersbugSomething isn't workingclibgagent CLI commands and HTTP client

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions