✨🧑‍💻 - feat reuse organization configuration and set up selected repositories in one guided session #538

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests.

What area does this improvement affect?

User Interface

What actions does this improvement affect?

Issue, Pull Request, Commit

Description of the idea or improvement

Adopt existing organization configuration in one repository or an explicit selection of repositories, with reviewed per-repository plans and truthful verification status.

Outcome and scope

A developer should be able to extend an existing Copilot installation to selected repositories in the current repository's organization without repeating the configuration questionnaire or re-entering shared Secrets. Keep the current single-repository path as the default. Selecting organization storage, reusing organization settings and selecting several target repositories are distinct decisions with plain-language explanations.

This is one combined product/design and implementation task for organization reuse plus multi-repository onboarding. Status: proposal; the Action-managed SDD must resolve the permission/discovery and installation-branch contracts below before declaring implementation readiness. Do not add these changes to the completed setup bugfix.

Evidence from real dogfooding

• platform setup issue #159 and bootstrap PR #166: 70 effective Variables validated, existing organization PAT preserved, zero repository Secrets created; repeated setup completed. Existing shared Variable values and visibility and Secret timestamps stayed unchanged.
• copilot bug #536 / fix PR #537: recommendation setup incorrectly requested Checks access that a fine-grained operator PAT could not provide.
• Existing selected organization Variables were initially invisible to platform; additive repository grants were necessary. Grant requests after Variable updates returned GitHub 404s in the first Apply and required explicit recovery. Reuse should avoid redundant writes and retain truthful partial receipts.
• Permission probes left 20 legacy jobs waiting for the obsolete coolify runner label. Their exact dogfooding runs were canceled, allowing the new workflow to proceed. Setup must account for probe side effects and cleanup.
• Runtime verification on master, official PAT health and agent CLI contract passed. Secret existence, runtime authentication and complete permission readiness remain different facts.

Recommended developer journey

1. Confirm the current checkout and inferred organization, exactly as today. Keep inspect/quick-adjustment entrypoints. Offer This repository (default) or Several repositories in vypdev. Personal repositories retain the single-repository route with an explanation.
2. Connect to GitHub for read-only discovery. In batch mode, show only repositories visible to the credential, paginate/search, show the current repository selected and require explicit additional selection. Archived/disabled/inaccessible targets have a clear reason. Never imply that a limited token discovered every repository in the organization. Offer a focused reconnect/manual repository-name route when discovery is incomplete; do not silently request access to every repository.
3. After choosing organization storage, offer Reuse existing organization configuration when recognized settings exist, or Customize configuration. Explain: shared values remain unchanged; selected repositories will be allowed to use them where needed. Support reuse independently for Variables and Secrets, including a mixed-scope installation.
4. Build and validate a typed configuration from recognized organization Variables. Skip answered questions and ask only for missing/invalid values and repository-specific choices. Show provenance: Organization, Repository override, New value, or Not verified. Reuse must not silently import package publishing, deployment, CI commands or approval producers from another codebase.
5. Preflight each selected target. Detect existing installation, default/development branches, effective overrides/shadows, required labels/forms/guidance, CI producer identities, required runner labels and access, and missing credential capabilities. An organization name existing in inventory does not prove repository access. Labels remain repository-owned; shared native issue types are reconciled once per organization, with no unrelated edits.
6. Review one batch summary with expandable per-repository plans. The default outcome is Create setup pull requests, one per changed repository, against each verified default branch. Show exact files, shared-resource access additions, new resources, overrides, branch names, required permissions and verification status. No-op targets produce no PR. Approval binds to this exact target/operation snapshot.
7. Apply each repository plan sequentially in the first version, show progress immediately and preserve links/receipts. Revalidate remote identities and revisions before every write. A failed target must not erase successful results. Retry only incomplete work after drift inspection and any renewed approval needed for changes.
8. Finish with a per-repository report distinguishing PR created, Waiting for merge, Installed; verification pending, Verified, Needs action, Canceled, and Unchanged. Creating a PR must never be presented as a completed installation.

flowchart TD
 A[Confirm current repository] --> B[This repository or selected organization repositories]
 B --> C[Connect and select explicit targets]
 C --> D[Reuse organization settings or customize]
 D --> E[Preflight and review per repository]
 E --> F[Approve exact batch plan]
 F --> G[Create setup PRs and report partial results]
 G --> H[Merge and verify each installation]

Text equivalent: confirm the origin, choose targets, reuse or customize, inspect each plan, approve, create PRs, then verify installation after merge.

Representative web content

Set up Copilot
Current repository: vypdev/copilot

Where do you want to set it up?
(*) This repository
( ) Select repositories in vypdev

Configuration
Use existing organization settings
Reuse model, agent roles and workflow settings. Shared values will stay unchanged.
Only missing settings and repository differences need your input.

Review 3 repositories
Repository       Configuration                 Next action
copilot          Already configured             No changes
platform         Inherit + 2 local settings     Create setup PR
service-api      PAT access missing             Review access

Primary action: Review setup plans

Pending: “Checking 3 repositories. Nothing has been changed.”
Action required: “service-api cannot use the organization PAT. Review the repository access addition.”
Blocked: “service-api was not changed because the credential cannot inspect its configuration. Reconnect and retry; the other plans are retained.”
Partial: “2 setup PRs created; 1 repository needs action. Existing PRs and shared-resource access are retained. Retry the pending repository.”
Complete: “2 installations verified; 1 repository already matched. Open each PR, verification run or configuration.”

Use one primary action per state, keyboard-accessible selection, counts and reasons in text, readable narrow/dark/light views and the existing en/es/fr/pt setup catalogs. Technical API/permission detail belongs in disclosure panels. Never render untrusted names/values as HTML, commands, mentions or arbitrary links.

Resource reuse and fixed safety rules

One user-facing source choice is enough: Reuse compatible organization configuration (recommended) or Customize. Derive Variable/Secret preservation from this decision and the existing storage scopes; do not add redundant independent reuse toggles.

Provider contracts: selected-repository grants must use the additive add-one-repository endpoints, preserving every existing membership. Reuse must never call a Secret create-or-update/upsert endpoint. GitHub documents no create-only compare-and-set for organization Secrets; if a required Secret is absent or uncertain, block that binding and guide explicit separate provisioning/customization followed by fresh inspection. Do not claim a single writer inside one operation prevents other administrators from changing organization resources. Existing Secrets remain untouched by reuse.

References: add a repository to an organization Secret, organization Secret upsert contract, organization Variable create contract.

• Inventory the organization namespace for candidates and the individual repository for effective access and shadows. Do not crawl other repositories to infer shared settings. An unavailable inventory is unknown, never empty.
• Preserve shared Variable values, visibility and all existing repository memberships. Existing valid values require zero update calls. Add only explicitly approved missing repository grants; keep global/private visibility unchanged. Read back the target's effective inventory after grants.
• Keep repository overrides visible. Resolve conflicts explicitly; never delete or replace an override silently to make inheritance appear successful.
• Secret values cannot be read back. Existing Secrets must not be copied, exported, displayed, logged or rotated by the reuse path. Keep the operator PAT separate from the runtime bot PAT.
• Current workflow PAT policy requires re-entry and always rewrites PAT. The new reuse path must explicitly amend that contract: reuse without replacement, audit available runtime capability/identity through a trusted installed/generated verification path, and label unavailable evidence as pending. Invalid required credentials block the affected target. No full permission or native-approval claim may be inferred from a successful /user read.
• Retain new-install/explicit replacement flows. A changed organization value or Secret replacement affects other consumers and needs a separate, prominently reviewed shared change; batch reuse must not perform it incidentally.
• A trusted health job must not execute PR-head code, custom scripts or a model request just to verify inheritance. Never weaken native approval, branch protection, runner-group access or deployment gates to make setup pass.
• Setup may prepare reviewed installation PRs only. No automatic merge, releases, tags, deployments, repository creation, organization-wide selection, cross-organization batch or arbitrary code execution.

Bounded configuration and recovery

Recommended defaults: current repository only; reuse recognized organization settings after selecting organization storage; PR delivery for batch; sequential targets; preserve all existing resources. Confirmed fixed v1 bounds: 1–25 explicit repository IDs in one organization per batch, no duplicates, one active Apply per session, one shared-resource writer per organization/operation, bounded provider retries. Show clear guidance to split larger batches. These limits were confirmed in SDD Q1 and must be encoded in the SDD and tested at boundaries.

Configuration precedence: explicit reviewed repository choices > existing repository override > accessible, compatible organization values > typed defaults, with unknown or unsafe bindings requiring review. Snapshot non-secret plans, target IDs, base revisions, resource fingerprints, operation identity and per-target receipts. Credentials stay in the paired local session and are excluded from resume/export artifacts. Reject stale approvals and future/invalid resume schemas. Cancel stops pending work and reports already created PRs/grants; do not pretend cross-repository rollback exists or remove grants another consumer may need.

Architecture and contract decisions

Reuse the existing shared setup coordinator, typed questionnaire, credential use cases, plan builders and provisioners through narrow per-target contracts. Add pure reuse/target-planning policies, semantic repository discovery and batch-journal ports, scope-aware provider adapters and redacted batch view models. CLI and web must project the same decisions; no duplicated orchestration in Svelte or terminal adapters. Provider DTOs/process/file/network access stay outside application/domain policy. Parse structured workflow/schema contracts and enforce dependency/cycle checks.

The following decisions must be encoded and validated in the Action-managed SDD (implementation direction is clarified below):

1. Discovery with a PAT already limited to one repository: show the limited view truthfully, support an explicit exact-target reconnect, and audit the final least-privilege capability set for all selected targets. Do not default to an all-repositories credential or introduce a mandatory GitHub App without a separate decision.
2. Fresh repositories cannot use an Action-created issue branch before installation. Recommended solution: a documented, installer-owned bootstrap namespace with exact base/ref shown in the approved plan, distinct from Action-managed work branches. Update collaborator guidance and recovery ownership explicitly; never invent a replacement managed branch or force-push. For already installed repositories preserve the existing Action-owned lifecycle.

Idempotency must reuse an existing setup PR identified by a durable operation marker and target identity, never duplicate it or overwrite human changes. Unknown create outcomes require inspection before retry. Cap notification output to one operation report and one setup PR per changed target. Report completed facts and retained effects before technical diagnostics.

Delivery sequence, tests and documentation

Deliver this as one coherent capability with reviewable stages: (1) organization reuse for a single repository, (2) explicit target discovery and preflight, (3) bounded batch PR creation and recovery, (4) shared UX, compatibility and dogfooding. Retain the current single-repository/local installation path and upgrade existing saved configurations without silently activating batch behavior.

Proposed minimum automated budget, to be refined by the SDD against actual risk: 104 distinct cases: pure typed import/precedence/planning 22; application state, retries, drift, cancellation and races 24; provider pagination/access/error mapping 18; workflows, labels/forms/guidance and bootstrap contracts 12; presentation/localization/accessibility/sanitization 16; integration, security and migration 12. Preserve repository coverage gates; cover all reachable branches of new pure decision policies. Use deterministic fakes, real SDK fixture transport and semantic UI assertions. Six controlled manual journeys must cover new/existing single repo, several mixed targets, missing selected access, partial Apply/retry, cancellation/resume and limited-token discovery. Include a regression ensuring repeated reuse performs zero existing shared-value/Secret writes and no duplicate grants or PRs.

Update setup-and-doctor, local-web-setup-assistant, configuration-management and PAT-onboarding SDDs and catalog evidence with implementation. Document the normal journey, permissions, ownership/precedence, batch limits, PR and verification states, migration and recovery in setup/authentication/configuration/troubleshooting docs. Update generated CLI/web assets and run specification/catalog, workflow, documentation, packaging, architecture and coverage validators. Do not count this proposal as implemented catalog evidence.

Observable acceptance / Definition of Done

• A complete organization configuration can be adopted without re-answering its questions, re-entering PAT or rewriting existing shared values; missing values alone are requested and verification limitations remain visible.
• A maintainer selects 3 explicit same-organization targets and sees exact effects and per-target readiness before a write; archived, inaccessible or unsupported targets cannot be silently included.
• A missing selected access grant is added without changing existing memberships or visibility; a same-name repository override remains visible until explicitly resolved.
• One configured/no-op target, one new target and one blocked target produce truthful independent outcomes and correct repository labels/forms/guidance; issue types are shared only at their proper organization scope.
• A failure after a grant or PR creation yields a partial receipt and inspectable links. Retry, replay, cancellation and unknown responses cannot duplicate or erase completed work.
• Changing a base revision, target set, credential authority or relevant shared configuration invalidates the approved plan before mutation.
• New-repository installation waits for human PR merge and reports runtime health independently. No model invocation, automatic merge/deploy or shared credential rotation occurs as a side effect.
• CLI and web use the same contracts; keyboard/narrow view and all four locales cover primary states. Each normative requirement has test/evidence and documentation traceability in the SDD; all gates and the numeric budget pass.

Current limitations or challenges

The current setup inspects the current checkout only. Organization inventories in GithubActionsResourceInspector primarily describe resources already available to that repository, so they cannot alone discover all organization candidates for a newly selected repository. preserveExisting preserves effective scope but is not a complete no-write reuse mode. PAT is explicitly excluded from preservation and must currently be supplied and audited again. The configuration panel supports existing-installation inspection and focused edits; a full installation still asks fresh configuration questions.

Applying organization storage is also different from choosing multiple installation targets: labels, files, branches, CI identities, runner requirements, overrides and health evidence remain target-specific. This was visible in the platform dogfood and should not become a bulk blind copy.

Expected impact

For an organization that has configured Copilot once, adopting it elsewhere becomes target selection, review of differences and setup PRs. Reuse removes redundant questions and writes and reduces shared-configuration replacement risk. A per-repository plan/status makes partial results and required human action understandable. The normal single-repository flow stays simple and the batch operation remains explicitly bounded and reviewable.

Alternatives considered

Repeated full setup per repository remains supported but repeats decisions and encourages unsafe copying. Scanning other repositories is unnecessary for shared Variable/Secret inventory and makes provenance unclear. Blind copy/all-repositories selection, automatic merging, organization-wide overwrites and a new mandatory hosted control plane are outside this proposal. A GitHub App can be considered later if PAT discovery/permissions make it necessary; it is not an assumed dependency.

Version of copilot

3.5.5; dogfood setup fix merged in PR #537 (develop)

Additional context or comments

Requested after completing the platform setup dogfood; keep dependency remediation in a separate platform bug issue. This task changes the public setup/credential and collaborator-branch contracts and needs contract-change/SDD review before implementation.

Repository evidence: src/application/usecases/setup/setup_wizard_use_case.ts; src/application/usecases/setup/setup_credentials_use_case.ts; src/application/policies/setup_configuration_storage_policy.ts; src/application/policies/setup_questionnaire_policy.ts; src/application/policies/setup_management_policy.ts; src/data/repository/github/github_actions_resource_inspector.ts and github_actions_resource_commands.ts.

Relevant SDDs: specs/setup-configuration-credentials-and-doctor.md; specs/setup-configuration-management.md; specs/local-web-setup-assistant.md; specs/setup-pat-permission-guidance-and-verification.md; specs/guided-bot-pat-onboarding.md. Follow specs/README.md and the canonical template.

Primary GitHub contracts: https://docs.github.com/en/rest/repos/repos#list-organization-repositories ; https://docs.github.com/en/rest/actions/variables#list-organization-variables ; https://docs.github.com/en/rest/actions/secrets#list-organization-secrets ; https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens . Provider behavior and token limitations require contract tests and controlled live evidence, not assumptions from resource names alone.

SDD ownership and implementation direction

The existing catalog capability setup-and-doctor owns this extension. Its existing specifications include specs/setup-configuration-credentials-and-doctor.md; the related web capability local-web-setup-assistant remains related evidence. A proportional companion for this issue should use the NEW, currently unregistered path specs/organization-configuration-reuse-and-batch-setup.md under the existing setup-and-doctor capability. Do not choose an already catalogued path for a companion, and do not invent a new owner ID merely because batch onboarding is new behavior. Proposed validated owner tuple: action companion, capabilityId setup-and-doctor, path specs/organization-configuration-reuse-and-batch-setup.md.

Resolve the two implementation choices as follows: (1) discovery shows the current credential's explicitly limited repository view, supports entering exact same-organization repository names, then audits/reconnects with a temporary operator PAT limited to the reviewed selected targets; unknown access stays blocked, and all-repository access is never assumed; (2) installation PRs for uninstalled targets use a documented installer-owned bootstrap namespace, with exact ref/base disclosed in approval and idempotent per-target receipts. Installed managed issue branches retain Action ownership. Update the generated collaboration contract before activating this new installation namespace. Deliver organization reuse first and batch PR orchestration second within this capability, retaining all visible safety/partial-state and test/documentation requirements above.