Separate stored GitHub PAT identity, VM assignments, and repository defaults

[hbrodin]

Problem

Coop currently identifies stored GitHub PATs by repository ([github.pat."owner/repo"]). This combines two different concepts: the identity of a credential and the repository for which it should be selected automatically.

A VM whose workspace contains several independent repositories may need a single PAT covering all of them. Conversely, two VMs working on the same repository may need different permissions, and several disposable VMs may intentionally share one credential. Repository-keyed credentials cannot express these relationships clearly.

Desired model

Separate three concepts:

1. Stored credential: a PAT with a user-chosen name, such as work-projects, whose secret remains in a host secret store.
2. VM assignment: a persistent reference from a VM to a stored credential.
3. Repository default: an optional mapping from a repository to a stored credential, preserving automatic selection for the common single-repository workflow.

For example:

stored credential: work-projects
repository default: myorg/frontend -> work-projects
VM assignment:     projects -> work-projects

Credential names and repository mappings do not define or restrict token permissions. GitHub enforces the actual permissions of the supplied token. A VM receiving a multi-repository token can use its full permissions regardless of its current directory.

User experience

Keep coop github setup-pat as the guided creation/storage workflow. Allow naming the resulting credential and optionally establishing a repository default. Users remain free to select multiple repositories when creating the token on GitHub; there is no need for a replacement generation workflow.

coop github status should list stored credentials, storage backends, and explicit VM assignments without revealing secrets. Per-VM status should identify the effective credential and why it was selected: explicit assignment, repository default, another existing auth mode, or no credential. Distinguish persisted assignments from dynamically inferred repository defaults; do not present a cached scope guess as verified GitHub permissions. The existing --probe checks secret retrieval, not GitHub authorization.

Assignment should be available for existing VMs and eventually at creation. Exact CLI spelling and configuration schema can be settled during implementation.

Selection and lifecycle semantics

• Explicit VM selection takes precedence over automatic repository selection and ambient credential fallback. With no assignment, retain existing behavior and default-off semantics.
• Respect an explicit invocation-level GitHub opt-out without deleting the saved assignment. Define its interaction with the separate one-shot clone-auth behavior rather than implying that today's --no-github means zero GitHub credential use everywhere.
• Apply credential selection consistently to first boot, cloning, restart, shell, exec, agent sessions, and applicable restore/reprovision paths.
• Resolve the credential reference when needed. Missing, malformed, or unreadable assigned credentials produce an actionable error; do not silently substitute a broader host credential.
• Detect conflicting managed GH_TOKEN / GITHUB_TOKEN overrides rather than silently letting them defeat the assignment. GitHub CLI gives GH_TOKEN precedence over GITHUB_TOKEN.
• Rotation updates subsequent resolutions for every referencing VM. Already-running processes retain credentials previously delivered; assignment changes are not revocation.
• Unassignment removes only the VM reference. Destroying a VM does not delete a shared credential. Deleting an in-use credential must report its dependents and must not cause unnoticed fallback. GitHub-side revocation remains distinct from local forgetting.
• Persist references, not resolved tokens, in VM state. Preserve secret redaction, storage permissions, and safe transport.

Use cases

Case	Expected behavior
One repo, one VM	Repository default provides automatic selection.
Several repo subdirectories, one VM	Explicitly assign a credential that covers the intended work.
Same repo, different VM permissions	Different explicit assignments.
Several VMs sharing a PAT	One stored credential, multiple references, one rotation.
Disposable/recreated VM	Credential survives; reassign it or use its repo default.
One VM requiring several distinct tokens	Not solved by a single assignment; per-host/repository credential routing is separate future work.

Delivery and compatibility

#468 is the independently deliverable first step: let a VM reference one of today's repository-keyed PAT entries. It must not wait for this credential-model migration.

This issue tracks the later separation of named credentials, repository defaults, and VM assignments, including backward compatibility for existing [github.pat] entries and assignments introduced by #468. Existing secret references should be reusable without asking users to regenerate tokens. Plan migration of setup, rotation, forgetting, completion, status/JSON, examples, and documentation together.

Related

• Assigning an existing pat to a coop vm #468 — minimal persistent VM assignment using existing stored PAT entries; first implementation slice.
• Creating a scoped gh token #73 — original scoped GitHub credential design discussion. This issue changes selection and ownership relationships, not GitHub's scope enforcement.