Evolve experimental `bootstrap` config into `add`/`add-wizard`

[mnkiefer]

Recent bootstrap and manifest-profile work is pushing gh aw beyond file installation and into repository-level configuration. The direction is reasonable, but the current shape risks overlapping responsibilities across bootstrap, add, add-wizard, and related manifest behavior. Our goal is to come up with a clear command model and manifest model before expanding the current bootstrap/configuration path further.

Context

The recent additions introduce or imply support for repository-level setup such as:

1. Repository variables
2. Repository secrets
3. GitHub App configuration
4. Interactive prompts for missing configuration
5. Idempotent repo-level setup during package installation

That makes the overall workflow more powerful, but it also raises design questions about where these capabilities should live and how they should relate to existing commands.

Discussion Points

1. Extend add with the ability to configure repository secrets, variables, and GitHub App credentials.
2. Keep the behavior idempotent so re-running the command does not duplicate, overwrite unexpectedly, or drift configuration.
3. Enforce a naming scheme or namespace for managed variables and secrets so package-managed configuration is predictable and auditable.
4. Decide whether this repository-configuration UX belongs in add directly or primarily in add-wizard.
5. Move the package YAML format toward something more declarative for repository configuration rather than continuing to accumulate imperative bootstrap-style pieces.
6. Reconcile how bootstrap, add, add-wizard, and doctor should fit together without overlapping responsibilities.

Open Questions

1. Should add become the canonical entry point for installing both files and repo-level configuration?
2. If yes, what is the non-interactive contract for secrets, variables, and GitHub App setup?
3. What remains bootstrap-specific versus what should become reusable package-install behavior?
4. How should the YAML manifest express repo variables, repo secrets, GitHub App setup, prompts, defaults, optional fields, and idempotency rules?
5. Should add-wizard just be the interactive front-end for the same underlying model?
6. What naming convention should be enforced for managed variables and secrets?

[pelikhan]

/scout design a declarative yaml fields to support specifying vars secrets apps

typecheck JSON schema friendly

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan — "design declarative YAML fields for vars/secrets/apps, typecheck + JSON-schema friendly"

Executive Summary

The cleanest, JSON-schema-friendly design is a single declarative config: block in aw.yml (the package manifest, kebab-case like the rest of that file) that mirrors two contracts you already interoperate with: reusable-workflow inputs/secrets (typed, required/default/description) for vars/secrets, and gh-aw's own existing github-app: frontmatter shape (client-id/private-key/permissions/owner/repositories — pkg/workflow/safe_outputs_app_config.go:21), extended with the official GitHub App-manifest registration fields (url/public/default-events), for apps. Keep each section a map keyed by NAME (not an array) so JSON Schema types it with additionalProperties + a propertyNames name pattern — this enumerates cleanly, forbids unknown fields, and validates with the santhosh-tekuri/jsonschema/v6 validator already wired into pkg/parser. The manifest declares requirements; add applies them non-interactively; add-wizard is the interactive front-end over the same model; bootstrap composes add; doctor checks drift.

⚠️ Reconcile casing first. aw.yml = kebab-case, aw.json = snake_case, github-app: frontmatter = kebab-case. Because this block lives in aw.yml, use kebab-case (default-permissions, not default_permissions) and reuse the existing github-app field names so there's one App vocabulary across frontmatter and manifest — not two.

Click to expand detailed findings, proposed schema, and answers to the open questions

Current state (what the design must fit)

• Package manifest aw.yml — schema pkg/parser/schemas/aw_manifest_schema.json (draft 2020-12, additionalProperties:false), Go struct repositoryPackageManifest (pkg/cli/add_package_manifest.go:191). Top-level fields today: manifest-version, min-version, name, emoji, description, license, includes/files/skills/agents. No vars/secrets/apps yet. This is the natural home — packages should declare what they need.
• Repo config .github/workflows/aw.json — schema repo_config_schema.json (draft-07), struct RepoConfig (pkg/workflow/repo_config.go:148): ghes, utc, action_pins, maintenance, etc. Consumer-side, not publisher-side.
• Existing convention to reuse: repoConfigSecretNamePattern = ^[A-Za-z_][A-Za-z0-9_]*$ (repo_config.go:44) — the GitHub Actions secret/variable name rule. Reuse it verbatim for propertyNames.
• Commands already exist: bootstrap, add, add-wizard, secrets set / secrets bootstrap, doctor — so the model just needs a shared data source.

Precedent 1 — reusable-workflow inputs/secrets (the typed contract to mirror)

GitHub's own on.workflow_call is the canonical GitHub-native shape for typed, declared inputs/secrets:

• inputs: description, required (bool), type (string|boolean|number), default.
• secrets: description, required (bool) — never a value.

Mirroring this gives authors zero new mental model and makes review predictable. (GitHub Docs — Reuse workflows)

Precedent 2 — apps: reuse gh-aw's github-app shape + GitHub App-manifest registration fields

You already ship a kebab-case App shape in workflow frontmatter (GitHubAppConfig, safe_outputs_app_config.go:21): client-id, private-key, permissions (map issues: write), owner, repositories, ignore-if-missing. Reuse those names. For registration (creating the App), layer in the official GitHub App-manifest parameters — url (required), public (bool), default-events (array), description — since the manifest flow generates app_id / private key / client secret; your declaration just names where those generated values are stored (secret names). (GitHub Docs — Registering a GitHub App from a manifest)

Precedent 3 — Terraform variable block (validation + sensitivity + idempotency semantics)

Terraform's variable block (type, default, description, sensitive, nullable, validation { condition, error_message }) is the reference for optional richer typing later — adopt enum/pattern now, leave room for a validation object. ([Terraform variable validation]((developer.hashicorp.com/redacted)

Proposed declarative shape (aw.yml)

manifest-version: "1"
name: My Agentic Package

# NEW: declarative repo-configuration contract (kebab-case, like the rest of aw.yml)
config:
  namespace: MYPKG_          # managed prefix; enforces auditability + idempotency
  variables:
    MYPKG_REGION:            # map keyed by NAME -> JSON-schema-friendly
      description: Deployment region
      type: string           # string | boolean | number
      required: true
      default: us-east-1
      enum: [us-east-1, eu-west-1]   # or: pattern: "^[a-z]{2}-[a-z]+-\\d$"
  secrets:
    MYPKG_API_KEY:
      description: Vendor API key
      required: true
      provider: custom        # reuse `secrets bootstrap`: anthropic|openai|copilot|custom
      # NEVER a value; only metadata
  apps:
    MYPKG_BOT:
      description: Bot for PR automation
      url: (example.com/redacted)          # App-manifest registration field
      public: false                     # App-manifest registration field
      permissions:                      # reuse github-app `permissions` map
        issues: write
        pull-requests: write
      default-events: [issues, pull_request]
      owner: my-org                     # reuse github-app `owner`
      store:                            # where generated credentials land (secret names)
        client-id: MYPKG_CLIENT_ID      # matches github-app `client-id`
        private-key: MYPKG_PRIVATE_KEY  # matches github-app `private-key`
      required: true

A workflow in the package then consumes them with the existing frontmatter, so the manifest declaration and the runtime reference share one vocabulary:

github-app:
  client-id: ${{ vars.MYPKG_CLIENT_ID }}
  private-key: ${{ secrets.MYPKG_PRIVATE_KEY }}

Why this is typecheck / JSON-schema friendly

Maps-keyed-by-name compile to a tight, closed schema (draft 2020-12, matches existing manifest):

"config": {
  "type": "object", "additionalProperties": false,
  "properties": {
    "namespace": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
    "variables": {
      "type": "object",
      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
      "additionalProperties": {
        "type": "object", "additionalProperties": false,
        "required": ["description"],
        "properties": {
          "description": { "type": "string" },
          "type": { "enum": ["string", "boolean", "number"], "default": "string" },
          "required": { "type": "boolean", "default": true },
          "default": {},
          "enum": { "type": "array" },
          "pattern": { "type": "string", "format": "regex" }
        }
      }
    }
    /* secrets, apps: same closed pattern */
  }
}

additionalProperties:false on each value object + propertyNames on the name gives you: unknown-field rejection, name-validation, and clean Go structs (map[string]VariableSpec) that yaml.Unmarshal into directly — no polymorphic UnmarshalJSON needed (unlike the maintenance bool-or-object field).

Answers to the issue's open questions

1. Canonical entry point? Yes — add becomes files + config:. bootstrap = add against a fresh/created repo (thin wrapper, no divergent config logic).
2. Non-interactive contract? add reads declared names and resolves values in priority order: CLI flags (--var K=V, --secret K=@env``) → env → aw.config.json answer file (stdin JSON). Missing `required` with no value → hard error in non-interactive mode. Secrets accept only references (`@ENV`, file, stdin), never inline.
3. Bootstrap-specific vs reusable? Only repo creation/clone/auth stays bootstrap-specific (already isolated in setupRepositoryRuntime, setup_repository.go). Everything config becomes reusable add behavior.
4. Manifest expression? The config: block above — declarative, defaults, optional/required flags, validation via enum/pattern.
5. add-wizard? Yes — pure interactive front-end that reads the same config: spec and prompts per declared field (type/enum drive the prompt widget). No separate model.
6. Naming convention? Enforce a namespace: prefix (validated by ^[A-Za-z_][A-Za-z0-9_]*$, the existing repoConfigSecretNamePattern). add writes/updates only namespaced keys → idempotent (skip if present & equal; --force/overwrite:true to replace), auditable, safe to re-run.

Idempotency rule (answers discussion point 2)

Managed keys carry the namespace; add diffs declared vs present: create if absent, skip if equal, and refuse to clobber non-namespaced keys. doctor reports drift (declared-but-missing / present-but-stale). Same guarantee action_pins gives today.

Recommendations

1. Add a top-level config: block to aw.yml, not to aw.json — packages declare requirements; the consumer repo receives them via add.
2. Reuse names you already have — reusable-workflow required/default/description/type for vars/secrets, and the existing github-app client-id/private-key/permissions/owner for apps (plus App-manifest url/public/default-events). One vocabulary, kebab-case, auditable at a glance.
3. Model each section as a map keyed by NAME with additionalProperties:false + propertyNames pattern — this is what makes it typecheck-clean and lets you generate Go map[string]Spec structs without custom unmarshalers.
4. Enforce a namespace: prefix for all managed vars/secrets to get idempotency + auditability for free; write only namespaced keys.
5. Keep add-wizard as an interactive renderer of the same spec; keep bootstrap a thin composition of add; use doctor for drift detection.

Key Sources

• GitHub Docs — Reuse workflows (inputs/secrets syntax)
• GitHub Docs — Registering a GitHub App from a manifest (parameters)
• [Terraform — Input variable validation/sensitive/nullable]((developer.hashicorp.com/redacted)
• Repo: pkg/parser/schemas/aw_manifest_schema.json, pkg/cli/add_package_manifest.go:191, pkg/workflow/repo_config.go:44 (secret-name pattern to reuse)

Suggested Next Steps

1. Write an ADR proposing the config: block + namespace rule (docs/adr/), referencing the reusable-workflow and App-manifest precedents.
2. Extend aw_manifest_schema.json with the closed config schema above; add ConfigSpec Go structs to repositoryPackageManifest.
3. Define the non-interactive resolver contract (flags/env/answer-file) and the idempotent apply/skip/force rules before touching bootstrap.

🔭 Intelligence gathered by Scout · 323.8 AIC · ⌖ 14.3 AIC · ⊞ 6.4K · ◷
_{Comment /scout to run again}

[pelikhan]

#45758