mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Native task completion independently verifies that declared PR deliverables are merged. > - Runs can already use an authorized managed GitHub connection to merge private PRs. > - Completion used the background credential resolver, which cannot select that run's managed identity. > - This pull request reuses operation-time identity and grant checks for completion verification. > - Agents can finish delivered work while unavailable grants and unverified merges remain blocked. ## Linked Issues or Issue Description Related: #22244 introduced the native PR merge gate. No duplicate fix was found in the open PR search. The roadmap's personal GitHub identity capability already covers the intended identity model. **What happened?** A native agent with a managed GitHub connection merges a private PR, then completion rejects it as not verified merged. The independent server-side check only tries legacy company token names or an instance token; it does not use the agent run's managed connection. **Expected behavior** Verify the merge with the run's current accepted GitHub identity, retaining current grant, membership, trust and company boundaries. GitHub must confirm the merge regardless of saved work-product metadata. **Steps to reproduce** 1. Configure a managed GitHub identity with access to a private repository and no legacy company GitHub token. 2. Use a native task run to merge and register a PR deliverable. 3. Finish the task. Before this change, the merge verifier cannot authenticate with the managed identity and rejects completion. ## What Changed - Bind completion credential lookup to the persisted company, native task and run. - Add a server-side completion credential path that shares managed grant, membership and trust checks with command credentials. Both active and succeeded runs capture identity under the existing task/run locks and reconcile pending steering acknowledgements before credential lookup. The command credential API still requires a running run. - Resolve credentials once for all PRs in a verification attempt; do no credential work for tasks without PR deliverables. - Preserve legacy fallback only for runs without a managed identity, and preserve the public-only restriction on server-environment credentials. - Add 23 PostgreSQL-backed authorization regression cases and document completion's identity behavior. ## Verification - Local checks cover revision `da2a3608b0375ead646bbbad35af853191488f07`. [Greptile review](https://github.com/paperclipai/paperclip/pull/22357#issuecomment-7023243798) is 5/5 on that revision with both prior threads resolved. [Required CI](https://github.com/paperclipai/paperclip/actions/runs/44625662403) passed on attempt 2 for the same revision, including typecheck, build, canary, server/runner suites and all eight e2e shards. - Red/green: the private-PR and identity-selection cases failed before the initial fix. Review exposed a succeeded-run reassessment failure and then an unsettled-steering gap in that path; each has a regression that failed on the reviewed commit and passes after its correction. Unresolved steering performs no token lookup, and durable acknowledgement selects the new person. The full worker test completes the task after automatic-review withdrawal while command credentials remain unavailable to the finished run. - `pnpm exec vitest run server/src/services/native-runtime/native-pull-request-completion.test.ts server/src/services/native-runtime/native-completion-feedback.test.ts server/src/__tests__/github-operation-credentials.test.ts server/src/__tests__/native-status-reassessment-work.test.ts server/src/__tests__/run-identity.test.ts server/src/__tests__/run-identity-projections.test.ts` — 222 tests pass across six files, on macOS arm64 with Node 25.6.1 and embedded PostgreSQL. - `pnpm --filter @paperclipai/server typecheck` — passes. - `pnpm verify --explain` — exits 2 because the subsystem documentation selects broad CI coverage. Required CI supplies the broader test/build coverage; this exit is not a full-suite pass. - The credential selection, steering, grant and company checks use real PostgreSQL state. Only the secret vault and GitHub HTTP transport are mocked; test requests never reach GitHub. - `git diff --check` and the staged secret/PII scan pass. No runtime artifacts are committed. - Earlier CI revision `4e42f64`: the [Build job](https://github.com/paperclipai/paperclip/actions/runs/44624163145/job/135914203042) ended after the runner received a shutdown signal and the workflow was cancelled. Its log does not show a compiler error before interruption; this interrupted attempt is not build verification. The current revision subsequently passed its own CI build on attempt 2. - Current revision canary: the [Canary Dry Run job](https://github.com/paperclipai/paperclip/actions/runs/44625662403/job/135919504493) was interrupted by runner shutdown before completion. The repository runner-loss classifier returns `lost: true` for its actual annotation and log. A targeted retry was refused while the workflow remained active. The same revision subsequently passed Canary Dry Run and the full workflow on attempt 2; the earlier interrupted attempt remains recorded here separately. - Live acceptance remains pending deployment; the change has not been deployed. ## Risks Completion now reads managed credentials through a server-side path shared with the existing authorization checks. Successful finished runs can be reassessed without granting them command execution credentials. Denied or unavailable identities must remain blocked without falling through to a different identity; regression tests cover revocation and company/task isolation. Credential lookup is shared within one bounded PR verification attempt, not cached across attempts. The existing HTTP deadline and merge proof requirements remain in place. No migrations or API contract changes. ## Model Used OpenAI Codex, `gpt-6.1-sol`, xhigh reasoning, with repository inspection, code editing and test execution. Context-window size is not exposed by the harness. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
308 lines
26 KiB
Markdown
308 lines
26 KiB
Markdown
# GitHub identity during agent execution
|
||
|
||
Shared agents use the GitHub connection of the person whose accepted instructions they are executing. Task ownership remains unchanged. GitHub is optional: ordinary work can start without a connection. Managed launchers provide a default author for local commits; private checkouts and authenticated API calls still require eligible credentials.
|
||
|
||
## Accepted instructions and continuations
|
||
|
||
`run_identity_contexts` records ordered revisions, stored message authors, originating causes, parent contexts, acceptance state, and redacted GitHub outcomes. `heartbeat_runs.active_identity_context_id` selects the current revision. Existing historical runs are not backfilled with inferred authorship.
|
||
|
||
Human messages use their stored authenticated author. Queued messages retain their delivery order. Accepting steering reserves a pending revision before delivery, then activates it after the provider acknowledgement. Rejected delivery leaves the prior revision active. An uncertain acknowledgement holds new credential acquisition; a later acknowledgement or its authenticated native event receipt reconciles the reservation. Replays cannot reactivate an older revision. Activation locks the task before the run, matching task and queue mutations so concurrent status changes cannot deadlock identity initialization.
|
||
|
||
Delegated work and interactions persist their originating context. Retries retain the originating run's active context. Background continuations carry their source run; dependency wakes use the task's continuation context, independently of its owner. Scheduled and webhook routines use the routine's responsible person; manual invocations use the caller, and edits preserve the routine's responsible person.
|
||
|
||
An accepted connection request continues for the addressed person who connected
|
||
the account. If an authorized transfer changed that person, the new run records
|
||
a connection handoff and keeps the original context as its audit parent.
|
||
Declined or automatically closed requests and ordinary approvals retain their
|
||
originating identity. Automatic retirement observes the addressee's existing
|
||
access; its wake does not attribute work to that person or authorize use of that
|
||
person's accounts. A request transfer alone cannot authorize that identity.
|
||
Retries keep the previous run's latest accepted context,
|
||
even when the retry still references the original request. If that context is
|
||
unavailable, a retry that references a connection request stops instead of replaying
|
||
the handoff or falling back to another person. An ordinary approval retry
|
||
restores the approval's saved originating context when the prior run never
|
||
initialized an identity, including an explicitly absent person. Otherwise,
|
||
an ordinary retry after a
|
||
preparation failure retains its existing responsible-user resolution when no
|
||
identity context was initialized. It prefers the source run's stored person
|
||
when available and can process newly authorized messages. It does not adopt
|
||
the task's old continuation identity. A new explicit operator action retains
|
||
precedence.
|
||
A transfer grants no
|
||
credential access; connection selection still checks the new person's grants and
|
||
policies.
|
||
|
||
## Managed GitHub operations
|
||
|
||
Executions with managed GitHub configured receive token-free `git` and `gh` launchers. Each launcher invocation resolves one eligible credential from the current run's accepted identity at operation start. A `gh` command's child Git processes inherit that command's captured identity; later steering does not change already-started operations.
|
||
|
||
When the broker returns a managed credential, `gh repo create`, its
|
||
`gh repo new` alias, and `gh repo fork` stop before they run. The message
|
||
names the connection's `create_repository` or `fork_repository` tool. Those
|
||
tools apply the connection's tool access rules, approvals, owner defaults, and
|
||
audit, which a raw `gh` command cannot. The agent then uses Git to push to the
|
||
new repository or to clone the fork. `--help` still runs. Without a managed
|
||
credential, `gh` runs these commands unchanged. This guidance is not a
|
||
security boundary: any command that receives the token can call the GitHub API.
|
||
|
||
A `git` command that never uses the network does not ask the broker. The launcher reads past the global options, such as `-C` and `-c`, and checks the subcommand against a short list (for example `status`, `diff`, `diff-files`, `write-tree`, `log`, `rev-parse`, `add`, `config`, `branch`, `checkout`). This includes the index comparison and tree writing used by workspace snapshots. An unknown subcommand or option still asks. `commit` and `var` still ask, because the managed author comes from the broker answer. The launcher keeps no broker answer between invocations and never writes a credential to a file.
|
||
|
||
GitHub credential capture reads the current task, project, and retained trust
|
||
policy bindings without transferring saved prompts, runner profiles, results,
|
||
or log excerpts. It keeps the existing task/run lock order and accepted-identity
|
||
reconciliation. Other identity callers retain their complete execution input,
|
||
including the native input required by project creation authorization.
|
||
|
||
Native runners retain a session-owned broker and launcher path across warm turns. The provider keeps an opaque transport token, not a GitHub credential or the previous run's signed capability. After acquiring exclusive session ownership, the controller binds the broker to the current company, agent, task, and run. Requests cannot choose another run or responsible person. The broker rejects requests while idle and discards credential responses if their run binding changed during acquisition. Each operation still rechecks the live run, accepted identity, grants, and trust policy through the shared credential resolver. Changing run IDs alone no longer replaces the provider process; changes to authentication mode, provider credentials, permissions, or other session configuration retain their existing retirement rules.
|
||
|
||
The session broker listens only on controller loopback and accepts only its authenticated GitHub credential operation. Remote executions reach it through the existing authenticated callback bridge. Its transport and launchers are retired with the provider session. If remote bridge startup fails, anonymous launchers keep ordinary work available; the next run retries setup with a fresh session. Controller restart/cold recovery still uses the existing checkpoint and process-recovery rules; the broker's in-memory authority is not persisted for adoption. A remote launcher reads its broker file again while it retries an unreachable broker, for up to 60 seconds. A command that runs during a controller restart thus uses the replacement broker when the restored controller publishes it. A removed broker file ends the wait at once.
|
||
|
||
The native GitHub callback bridge uses HTTP/2 only when the server-selected
|
||
`enableSandboxDuplexBridge` flag and the sandbox's verified duplex capability
|
||
permit it. Missing settings, unsupported providers and failed channel startup
|
||
keep the authenticated file bridge. Changing the server flag retires a retained
|
||
warm bridge at the next normal run boundary, before a retained instruction copy
|
||
is claimed. A lost HTTP/2 channel also makes the broker unavailable and retires
|
||
that warm session at its next admission. An unchanged flag and a healthy broker
|
||
permit reuse. Normal session cleanup closes the channel as an orderly completion.
|
||
This selection changes transport only; operation-time credential checks remain
|
||
the same. Local and SSH execution retain their existing transport.
|
||
|
||
Other adapters continue using the run-scoped signed capability and public broker endpoint. That endpoint rejects browser origins and session cookies, validates a distinct signed runtime scope, and rechecks the company, agent, and live run. GitHub credentials are returned only to the managed command process, never persisted in identity history or injected into the long-lived provider process.
|
||
|
||
Low-trust executions cannot receive raw GitHub credentials, including dedicated
|
||
agent tokens. The broker rechecks current agent, project, task, and retained run
|
||
policies before credential resolution. An external guest's internal sponsor is
|
||
accountable for the task, but does not authorize using the sponsor's account.
|
||
Read-only access must use separately authorized tools that enforce that boundary.
|
||
|
||
Server-side Git operations and GitHub gateway calls follow the same selection rules. Approved gateway operations retain their signed originating identity. Connection audience and tool policies continue to apply to the selected person's connection. Native catalogs remain stable across identity changes, but each invocation resolves the selected grant again. Personal OAuth secret declarations survive connection pauses and metadata edits.
|
||
|
||
Native task completion verifies PR merges with the run's current accepted GitHub
|
||
identity, using the same live grant and trust checks as managed commands. A
|
||
revoked or unavailable managed connection cannot fall back to another identity.
|
||
Runs without a managed identity retain the legacy company-token lookup and the
|
||
public-repository restriction on instance-wide tokens. A saved work-product
|
||
status is never proof of a merge; GitHub must confirm it before completion.
|
||
Server-side reassessment may recheck a succeeded run using its persisted accepted
|
||
identity and current grants. That check does not permit command credential
|
||
acquisition after the run ends.
|
||
Completion identity capture uses the same task/run locks and steering
|
||
acknowledgement reconciliation as command credential capture. An unresolved
|
||
steering reservation blocks credential lookup, including after a run succeeds.
|
||
|
||
Managed commands disable ambient Git credential helpers, Git global/system configuration, host GitHub CLI configuration, and host SSH identity access. Per-operation GitHub CLI configuration is isolated in a writable configuration directory beneath the managed launcher directory. Missing credentials clear previous author and token values; no teammate, standing delegation, host token, or company-default user's account is substituted. Anonymous/local operations remain available where supported.
|
||
|
||
OpenCode retains the controller-projected GitHub broker environment through
|
||
runner startup and provider startup. Shell operations acquire credentials for
|
||
the active run through that broker. They do not require a persistent GitHub CLI
|
||
login or inherit an ambient host broker capability.
|
||
|
||
Claude through native ACPX retains the controller-projected broker URL and
|
||
session/bridge capabilities alongside its managed launcher paths through both
|
||
the Rust daemon-to-sidecar and TypeScript provider launch boundaries. Both isolated
|
||
and preconfigured homes use this transport for shell `git` and `gh` operations.
|
||
These capabilities stay out of persisted session environment data. Raw GitHub
|
||
tokens remain confined to each managed command; ambient host capabilities and
|
||
task-supplied broker overrides are excluded. A working connector tool alone does
|
||
not prove that the terminal received its broker transport.
|
||
|
||
The Rust sidecar launch accepts this transport only for Claude with a nonempty
|
||
managed launcher directory. Existing saved sessions retain their profile and
|
||
checkpoint format. A running provider needs its normal retirement and restart
|
||
to receive the repaired launch environment; reconnecting the GitHub account
|
||
does not repair a process that already started without the transport.
|
||
|
||
Without a managed identity, local commits default to
|
||
`Paperclip <noreply@paperclip.ing>`. The launcher writes this token-free default
|
||
to a private per-operation global Git configuration file, removed on exit.
|
||
Repository identity and `git -c user.name=... -c user.email=...` override it.
|
||
The launcher leaves author/committer environment variables unset instead of
|
||
guessing the host user's details. `git config --global` changes only this
|
||
temporary file; use repository configuration for persistent overrides.
|
||
If the private configuration directory or default author file cannot be prepared,
|
||
Git ignores the incomplete file. Local commits still require an explicit
|
||
repository or command identity when no managed identity is available. A failed
|
||
default author write does not remove valid managed credentials. Managed shell profiles
|
||
remove empty identity overrides after environment merging, so agents do not
|
||
need to unset them per command. A captured managed identity still takes
|
||
precedence over repository configuration.
|
||
|
||
Remote launchers prepend their directory to the execution target's effective
|
||
`PATH`. An explicit remote `PATH` override is preserved; otherwise Paperclip
|
||
reads the provider's environment before staging the launcher shell files.
|
||
This keeps legacy NVM and user-local agent installations available alongside
|
||
newer images with system-wide CLIs. The generated shell files retain that
|
||
combined path with managed `git` and `gh` first. The launcher directory has
|
||
its own CommonJS package scope, so the extensionless Node launchers work
|
||
inside repositories that declare `"type": "module"` without changing the
|
||
project's package configuration. Sandbox command checks use
|
||
the same sanitized environment as execution, so a CLI visible only in the
|
||
provider's default environment cannot pass the launch check. Failed path
|
||
discovery stops startup instead of silently falling back to a minimal path.
|
||
|
||
Providers that declare concurrent sync support stage at most three independent
|
||
launcher files at once. Other providers keep serial staging. Each file retains
|
||
its content hash, upload lock, integrity check and atomic rename. A failed batch
|
||
settles all started uploads before startup rejects; later files and the final
|
||
permission step do not start. This changes startup scheduling, not credentials
|
||
or callback transport selection.
|
||
|
||
Scripts that previously read a persistent `GH_TOKEN` must use managed `git`, `gh`, or GitHub gateway tools. Managed execution skips legacy GitHub token bindings in agent, environment, project, and routine configuration before secret preflight. Configure personal or dedicated access through the GitHub connection instead. Directly invoking an unmanaged executable or retaining a token obtained during an earlier invocation is outside the managed invocation contract.
|
||
|
||
## Legacy hosts and networking
|
||
|
||
When no managed GitHub connection is installed for an agent, standard-trust
|
||
local and SSH executions retain that execution host's existing Git and GitHub
|
||
CLI credentials, configuration, credential helpers, and SSH agent. Paperclip
|
||
does not import controller credentials into an SSH target. Sandbox, plugin,
|
||
and low-trust executions do not receive this compatibility fallback. Once a
|
||
managed connection is configured, unavailable or revoked access never falls
|
||
back to host authentication. Switching modes replaces the provider process
|
||
while preserving the settled conversation.
|
||
|
||
Runner network access is independent of GitHub credentials. The controller
|
||
enables networking for standard-trust execution. Low-trust runs and runners
|
||
without a controller network decision retain a restricted default. An operator
|
||
can set `PAPERCLIP_RUNNER_NETWORK_ACCESS=disabled` to restrict normal execution;
|
||
user environment bindings cannot override that decision. Outer execution-
|
||
environment network restrictions still apply. The controller projects the assigned worktree's Git metadata paths so
|
||
Git can operate without exposing unrelated workspace or provider state. The
|
||
sandbox also receives read access to validated provider executable resources
|
||
and the target host's DNS and CA files, including resolver symlink targets
|
||
outside `/etc`. Provider credential directories remain isolated.
|
||
|
||
A managed broker outage does not prevent local Git operations. Launchers clear
|
||
credentials and run the command without authentication, with a redacted error
|
||
category identifying configuration setup, transport, or capability rejection.
|
||
They do not retain a previous operation's token or replay a GitHub operation.
|
||
|
||
Healthy eligible grants for the same stable GitHub account ID take precedence
|
||
over duplicates with failed health checks. Credential acquisition can retry
|
||
once against another grant for that same principal and account, before any
|
||
GitHub operation begins. Run identity diagnostics include the selected
|
||
connection and grant IDs, without credential values. Access-refresh conflicts
|
||
retry once against current state and never turn a concurrency conflict into
|
||
a reconnect requirement.
|
||
|
||
## Dedicated accounts and diagnostics
|
||
|
||
An explicit dedicated-agent grant overrides personal selection. Revoked, disabled, unavailable, or ambiguous dedicated grants do not fall back to a person's account. Removing the dedicated configuration restores personal selection.
|
||
|
||
Connection setup and permissions display: “This agent uses this GitHub account for everyone's work, instead of the person giving instructions.”
|
||
|
||
The GitHub permissions page shows repositories across all connected accounts in one scrollable list. It has no account filter or repository search. Repository icons, private-repository indicators, refresh, and GitHub configuration links remain available. The “Add More Repos on GitHub” button opens GitHub’s app installation and repository-access setup.
|
||
|
||
Multiple eligible connections for the same GitHub account are treated as one
|
||
identity, using GitHub's stable account ID rather than its login. The resolver
|
||
selects an available grant, preferring the newest authorization with a stable
|
||
ID tie-breaker. Duplicate eligibility includes an active credential record with
|
||
the correct owner, the OAuth access-token reference, and repository access
|
||
metadata. It keeps that grant's credential and connection policy together;
|
||
it does not combine repository access or bypass connection audiences. Distinct
|
||
accounts or unidentifiable duplicate grants remain ambiguous. Managed commands
|
||
print the redacted reason when GitHub access is unavailable, while unrelated
|
||
local operations can still proceed without credentials.
|
||
|
||
Run details show identity revisions and redacted GitHub results: responsible person, selected login when available, personal/dedicated source, and an unavailable reason. Tasks do not receive an additional identity indicator or takeover action.
|
||
|
||
## Deployment and verification
|
||
|
||
Deploy the schema, server broker, launcher staging, and runtime environment contract together. Already-running processes retain their original environment; only newly dispatched processes receive the broker contract. Run-scoped capabilities remain valid only while their bound run is active.
|
||
|
||
Focused coverage lives in `run-identity.test.ts`, `github-operation-credentials.test.ts`, and `github-launcher.test.ts`, alongside the native steering, gateway, routine, and callback-bridge suites. Live acceptance additionally requires two authenticated Paperclip users, two authorized GitHub accounts, and a designated disposable repository for push verification. Local commit metadata and mocked API results do not replace that live push test.
|
||
|
||
### Release procedure
|
||
|
||
1. Back up the instance database using the normal deployment procedure.
|
||
2. Build and deploy one revision containing migrations 0240–0245, the server broker, managed launchers, and the runner artifacts. Run the standard pending-migration check before admitting new runs. These additive migrations are safe to replay and do not infer authorship for historical runs.
|
||
3. Let pre-rollout executions finish with their original runtime contract. New executions must have an active identity context and the managed launcher capability before provider startup.
|
||
4. Check one ordinary run without a GitHub connection, then an authenticated GitHub operation. Inspect the run details for the responsible person and credential outcome. Verify a queued continuation on the same conversation.
|
||
5. If rollback is needed, finish or explicitly stop executions using the new broker before removing its endpoint. Keep the additive schema and identity history. Do not drop identity columns or tables to roll back application code.
|
||
|
||
Remote acceptance uses the existing paid runner workflow with a narrow selection. Run it against the same immutable revision as the release; a successful local test does not qualify a different remote runner artifact.
|
||
|
||
Identity history survives deletion of the originating agent or run, so surviving
|
||
subtasks and approvals retain their responsible person. The company foreign key and company-deletion service remove
|
||
these company-scoped records when their company is deleted. Run-scoped adapters remove their managed launcher files at the terminal boundary.
|
||
Native warm sessions retain their token-free launchers and inactive broker until
|
||
session retirement; environment deletion and orderly controller shutdown close
|
||
idle owners first. Cleanup failures are logged and do not change the run result.
|
||
|
||
Remote native sessions verify the GitHub callback bridge from inside their execution
|
||
environment before publishing the launcher environment. The probe authenticates
|
||
to the inactive broker and acquires no GitHub credential. If the HTTP/2 bridge
|
||
fails this startup check, the controller closes it and tries the existing file
|
||
bridge once. Both transports use the same live identity and credential resolver.
|
||
An unverified final bridge is stopped before anonymous launchers are returned.
|
||
This startup fallback cannot replay an agent command. A later HTTP/2 loss
|
||
still makes the warm session unavailable for reuse.
|
||
|
||
## Project authorization for background repository work
|
||
|
||
Background provisioning and workspace maintenance have no responsible task user.
|
||
They must not retain a task's identity. A signed-in project workspace writer can
|
||
select their own active, company-installed GitHub Connector grant in project
|
||
settings and explicitly authorize the project. The binding stores the exact grant
|
||
ID and consenting user, never a credential. Revocation records a project lifecycle
|
||
event so subscribed providers can reconcile the change.
|
||
|
||
`GET /api/projects/:id/git-authorization` returns the current binding and only the
|
||
viewer's eligible personal grants. `PUT` accepts `{ grantId }` or `{ grantId: null }`.
|
||
Agents cannot create this standing consent. Project workspace writers can remove it.
|
||
Core rechecks membership, Connector installation/enablement, grant status, and
|
||
repository metadata on each background use. Public repositories never require
|
||
a connection or credential. Private repositories wait for authorization before
|
||
provisioning starts, so missing consent cannot leave a failed anonymous clone.
|
||
Repository selections retain the same visibility metadata used by the UI lock.
|
||
Legacy workspaces use existing Connector catalog metadata, with anonymous
|
||
GitHub discovery only when visibility is unknown. Unknown visibility defers
|
||
provisioning; it is never assumed public. It never substitutes another grant
|
||
when the selected one fails. Replacing a grant requires explicit reauthorization.
|
||
Project consent follows the selected connection's current GitHub repository access,
|
||
including repositories added to the project later. It does not create a second
|
||
repository approval list. Project repository editors may add sources within that
|
||
connection's access; manage permitted repositories in the GitHub connection.
|
||
Background export also rechecks the consenting user's project read access and the
|
||
project's existing trust policy. Low-trust or unverified projects cannot export a
|
||
raw credential through standing consent.
|
||
Cloud owner access is rechecked through current Cloud authority and the managed
|
||
owner-elevation setting on every private background export; saved local admin
|
||
roles cannot replace that authority. An unavailable authority check cannot confer
|
||
owner access, though explicit project membership still applies.
|
||
|
||
The trusted plugin capability `projects.git-credentials` enables
|
||
`ctx.projects.resolveGitCredential(projectId, workspaceId, companyId)`. The host
|
||
binds requests to the active project lifecycle or workspace operation; data, UI,
|
||
tool, and proactive calls do not carry this authority. Repository URLs come from
|
||
stored project workspaces. Foreground preparation uses the live run's accepted
|
||
identity and standard trust checks, even when background project consent exists.
|
||
Maintenance ignores originating run/agent context and uses project consent only.
|
||
Core delivery-proof cleanup uses the same project consent before contacting GitHub,
|
||
bound to the provider's stored source project and repository. It repeats authorization
|
||
for the final proof before removal; a changed source or revoked grant retains storage.
|
||
After archival, existing consent remains usable only for host-issued workspace
|
||
inspection and removal. New provisioning and new consent remain blocked.
|
||
|
||
The provider receives a transient GitHub token with its existing provider
|
||
permissions. This is not a repository-scoped or read-only token minting API.
|
||
Only grant-listed repositories can trigger background export. Plugins must never
|
||
save tokens in entities, state, configuration, operation receipts, or logs, and
|
||
must send them only to trusted execution infrastructure over HTTPS. Revocation
|
||
prevents subsequent credential acquisition; it cannot recall a token already
|
||
sent to an in-flight operation. Existing tasks and Git credential fallback rules
|
||
outside this plugin API are unchanged.
|
||
|
||
### Plugin-owned task command environments
|
||
|
||
Task-only environment plugins negotiate `githubCredentialBrokerVersion: 1` and
|
||
receive the current run's broker capability through structured preparation.
|
||
Core does not prescribe executable names, files, scripts, or a staging layout.
|
||
The plugin owns its command implementation and isolates ambient host identity.
|
||
See [the plugin broker contract](plugins/PLUGIN_RUNNER_EXECUTION.md#operation-time-github-credentials).
|
||
These task providers use the signed, run-scoped public broker endpoint; they do
|
||
not require the controller's remote shell or session callback bridge. Warm task
|
||
preparation replaces the capability before the next run's commands. Credentials
|
||
are still captured separately for each operation through the same live resolver.
|