mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-14 08:26:46 +02:00
Devin FoleyandPaperclip
165b10bd98
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The GitHub connector lets agents use repository tools through MCP. > - GitHub excludes Actions from its default MCP toolsets. > - Approval of Actions permissions therefore does not make workflow tools appear in Paperclip. > - This pull request adds Actions to the requested toolsets for discovery and execution. > - Users can refresh existing connections and use workflow tools under the existing access rules. ## Linked Issues or Issue Description **What happened?** GitHub Actions tools remain absent after the GitHub App receives Actions read/write access and the user refreshes actions in Paperclip. Paperclip does not request the Actions MCP toolset. **Expected behavior** Authorized GitHub connections expose workflow tools, including `actions_run_trigger` with `method: "run_workflow"`, so agents can dispatch an existing release workflow. **Steps to reproduce** 1. Connect GitHub to Paperclip with access to a repository that has a dispatchable workflow. 2. Grant the GitHub App Actions read/write permission and approve the installation update. 3. Refresh the connection's actions in Paperclip. 4. Observe that the workflow tools are absent. **Paperclip version or commit** Base commit: `fae698031`. **Deployment mode** Hosted instance with a managed GitHub connection. The same missing header affects PAT connections. No matching public issue or pull request was found in the duplicate search. ## What Changed - Send `X-MCP-Toolsets: default,actions` through the shared GitHub MCP header helper. This covers discovery, refresh, and execution for existing and new managed or PAT connections, including legacy rows identified through `transportConfig`. - Test catalog refresh, tool risk classification, and workflow dispatch through a mock MCP server. - Document tool names, workflow arguments, required GitHub permissions, and the refresh step. ## Verification - Passed both affected test suites: `pnpm exec vitest run server/src/__tests__/tool-access-service.test.ts server/src/__tests__/tool-gateway.test.ts` (391 tests). - Passed `pnpm check:token-gates` and `git diff --check`. - Live provider check: the default catalog returned 45 tools. `default,actions` returned 49 tools, with no tools removed. The four added tools were `actions_get`, `actions_list`, `actions_run_trigger`, and `get_job_logs`. - Live `actions_get` / `get_workflow` call succeeded. No workflow was dispatched during live verification. - Passed `pnpm -r typecheck` and `pnpm build` with the existing Rust toolchain added to PATH. - Rechecked server typecheck and build after the legacy-connection fix; both passed. - The full local test run has reported three skills-cache failures in `company-skills-service.test.ts`. All three reproduce on the untouched base commit (`fae698031`) on this macOS host: runtime-cache directory renames fail with `EACCES`. The full run remains in progress. - Greptile: 5/5 on `7d391e3c7`, with no unresolved review threads. - After deployment, use **Refresh actions** on an existing GitHub connection and verify the workflow tools appear. ## Risks - Refreshed GitHub catalogs expose more tools. Existing access, approval, and quarantine rules still apply. `actions_run_trigger` keeps GitHub's destructive classification because it also supports cancellation and log deletion. - GitHub still enforces token and installation permissions. Dispatch requires Actions write permission and a workflow with `workflow_dispatch`. - No database migration or saved connection edit is required. ## Model Used OpenAI GPT-6 through Codex, with code execution and tool use. The exact serving model ID and context window are not exposed in this session. ## 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 - [ ] 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>
167 lines
8.7 KiB
Markdown
167 lines
8.7 KiB
Markdown
# GitHub managed connection
|
|
|
|
GitHub is a Paperclip Cloud-managed GitHub App connection with an advanced PAT
|
|
compatibility method. Cloud owns the fixed public OAuth callback and signed
|
|
webhook inbox; provider tokens are sealed to the enrolled instance and stored
|
|
only in its existing encrypted secret system.
|
|
|
|
## Self-hosted setup
|
|
|
|
The Access step uses **Continue** to open the local setup screen.
|
|
**Continue to GitHub** on that screen starts the provider handoff. The first
|
|
button does not imply that the browser is leaving Paperclip yet.
|
|
|
|
A self-hosted instance needs one Paperclip Cloud approval before its first
|
|
managed connection. After approval, setup returns to step 2 and continues to
|
|
GitHub without another instance approval or a service restart.
|
|
|
|
If an unapproved enrollment link expires, return to setup and select
|
|
**Continue**. Paperclip asks the server for a valid link. The server reuses a
|
|
live pending enrollment or replaces an expired one; this does not revoke or
|
|
repeat an existing instance approval.
|
|
|
|
## Identity resolution
|
|
|
|
Every MCP call, `gh` invocation, native Git operation, checkout, health check,
|
|
and webhook binding uses the same order:
|
|
|
|
1. An active dedicated GitHub grant for the current agent.
|
|
2. The active personal GitHub grant owned by the run's `responsibleUserId`.
|
|
3. For automated work without a responsible user, a personal grant only when
|
|
an existing standing delegation names the agent.
|
|
4. Legacy `GH_TOKEN`/`GITHUB_TOKEN` only when no managed GitHub connection is
|
|
configured for the company.
|
|
|
|
An unavailable or ambiguous managed identity fails visibly. It never falls
|
|
through to another person, an organization credential, or a legacy token.
|
|
Agent grants are company-scoped, have exactly one `subjectAgentId`, cannot be
|
|
organization defaults, and are installed only for that agent.
|
|
|
|
The connection installation is the credential owner's consent boundary. A
|
|
personal setup may target every agent or a selected set, and runtime resolution
|
|
considers only an enabled, active connection installed for the current agent.
|
|
Within that boundary, Paperclip treats the run's server-resolved
|
|
`responsibleUserId` as its credential principal, including for automated work;
|
|
agents cannot choose or spoof this field. The owner must still be an active
|
|
non-viewer company member at each use. A standing delegation is needed only
|
|
when a run genuinely has no responsible user.
|
|
|
|
## Credential lifecycle
|
|
|
|
The production, staging, and development GitHub Apps deliberately disable
|
|
user-to-server token expiration. The resulting long-lived access token is
|
|
checked with GitHub's `/user` endpoint every 30 days, together with installation
|
|
and repository summary refresh. Routine continuity requires no browser visit.
|
|
|
|
If GitHub returns an expiring access token and rotating refresh token instead,
|
|
Paperclip stores both encrypted and:
|
|
|
|
- refreshes at least one hour before access expiry;
|
|
- forces a rotation at least every 30 days while the instance is active;
|
|
- serializes refresh through the existing database refresh lease and compare-
|
|
and-swap update;
|
|
- atomically advances both secret values before clearing the lease;
|
|
- retries one forced refresh after a provider `401`.
|
|
|
|
Only an unrecoverable provider invalidation marks a grant
|
|
`needs_reauthorization`. Installation removal or suspension is reported as an
|
|
installation-health failure, not as token expiry.
|
|
|
|
## Repository access
|
|
|
|
OAuth completion verifies `/user`, every page of `/user/installations`, and every
|
|
page of each installation's accessible repositories. Setup remains incomplete
|
|
until at least one installation and repository are available. Paperclip stores
|
|
the authenticated username and a grant-scoped display snapshot containing only
|
|
repository IDs, full names, installation IDs, and private-repository flags. GitHub stays authoritative:
|
|
this snapshot never authorizes repository access.
|
|
|
|
The permissions page shows repositories across authorized accounts by default.
|
|
Use the account filter and search to narrow the list. The list scrolls after
|
|
about ten rows and marks known private repositories with a lock. Configure on
|
|
GitHub opens the app account chooser so users can add or update organization
|
|
access. Refresh access after changing the selection. Older snapshots omit the
|
|
private flag until refreshed. If a legacy grant lacks its app chooser URL,
|
|
**Load GitHub configuration** refreshes access and recovers the app slug from
|
|
GitHub installation metadata. The page does not substitute a single-installation
|
|
settings URL for the account chooser.
|
|
|
|
The permissions page shows the authenticated GitHub account and the complete
|
|
accessible repository list. **Refresh access** reloads it from GitHub. Older
|
|
grants and grants invalidated by newer installation lifecycle events prompt for a
|
|
refresh instead of presenting a stale list. The page links to GitHub's
|
|
installation management page. Selected repositories are recommended; all-
|
|
repository access retains its warning.
|
|
|
|
Fresh local test-drives use production Paperclip Cloud. Instance enrollment
|
|
and provider enablement are separate: enrollment alone does not enable GitHub
|
|
OAuth. Production must advertise the `github.code` profile (see Cloud's
|
|
`docs/github-connector-deploy-bootstrap.md`). If it is unavailable, setup
|
|
preserves the sign-in intent and offers a retry instead of silently switching
|
|
to a personal access token. A successful retry preserves the chosen audience.
|
|
|
|
## GitHub Actions tools
|
|
|
|
Managed and PAT connections request `X-MCP-Toolsets: default,actions` for MCP
|
|
discovery and invocation. GitHub's default catalog excludes Actions; granting
|
|
Actions permissions alone does not expose workflow tools. Existing connections
|
|
can use **Refresh actions** after upgrading to discover the added tools.
|
|
The normal catalog, access, approval, and quarantine rules still apply.
|
|
|
|
To dispatch an existing workflow, use `actions_run_trigger` with
|
|
`method: "run_workflow"`, the repository owner and name, `workflow_id`, `ref`,
|
|
and any workflow `inputs`. The workflow must declare `workflow_dispatch`.
|
|
The GitHub App installation or fine-grained PAT needs **Actions: Read and
|
|
write** for the repository. App owners set that permission on the GitHub App
|
|
registration; installation owners must approve an increase before it takes
|
|
effect. Paperclip's action controls do not grant GitHub permissions.
|
|
|
|
The tool also supports rerunning and cancelling runs and deleting run logs.
|
|
It retains GitHub's destructive classification. Read tools include
|
|
`actions_list`, `actions_get`, and `get_job_logs`.
|
|
|
|
Provider references: [MCP toolset configuration](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md)
|
|
and [workflow dispatch permissions](https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event).
|
|
|
|
## Webhooks
|
|
|
|
Paperclip Cloud verifies `X-Hub-Signature-256` against the exact bounded request
|
|
body before parsing, deduplicates by `X-GitHub-Delivery`, and persists a minimal
|
|
normalized event before returning `202`. Raw webhook payloads are discarded.
|
|
When registering an active binding, Paperclip sends the current user token only
|
|
inside the signed, payload-bound broker request so Cloud can verify access to
|
|
that exact installation; Cloud neither logs nor persists that proof token.
|
|
Deliveries fan out independently to every enrolled instance bound to the GitHub
|
|
installation and are sealed to each instance's public key.
|
|
|
|
The instance polls with backoff, stores a company-scoped idempotency receipt,
|
|
and acknowledges only successful applications. A merged pull request updates
|
|
its matching external-object snapshot and immediately runs the existing merge-
|
|
confirmation resolver. It wakes the assignee only when that interaction's
|
|
continuation policy requests it; unrelated Paperclip issues are not closed.
|
|
The periodic GitHub merge sweep remains the reconciliation fallback.
|
|
|
|
Installation lifecycle events refresh or invalidate installation summaries and
|
|
remove obsolete Cloud bindings. Activity records contain event identifiers and
|
|
outcomes but no webhook content. GitHub webhook content is never first-party
|
|
telemetry.
|
|
|
|
## Run projection
|
|
|
|
The resolved token is leased at run start as an audited class-3 secret and is
|
|
projected only into the child process:
|
|
|
|
- `GH_TOKEN`, `GITHUB_TOKEN`, and an internal credential-helper environment key;
|
|
- `GIT_TERMINAL_PROMPT=0`;
|
|
- process-scoped `GIT_CONFIG_COUNT/KEY_n/VALUE_n` entries that clear ambient
|
|
helpers, install a `github.com`-only helper, and rewrite GitHub SSH remotes to
|
|
HTTPS;
|
|
- author and committer identity using
|
|
`<numeric-id>+<login>@users.noreply.github.com`.
|
|
|
|
Tokens never appear in arguments, URLs, files, logs, events, or model context,
|
|
and the projection never replaces `HOME`.
|
|
|
|
Cloud deployment and exact GitHub App registration settings live in
|
|
`paperclip-cloud/docs/github-connector-deploy-bootstrap.md`.
|