d627632874
Docs for parent release `v2026.1106.0` (`d69631b0`), up from `v2026.1023.0` (`1b4c8038`): 515 parent commits. ## How this branch was built The tag is 914 commits behind what `nightly` has drafted, so this branch isn't cut from `nightly` HEAD. It starts at nightly commit `1952052` (parent `043f2514`), 19 commits before the tag, then adds: - the `main` hotfix (#160) - the sync tooling from `nightly` - docs for those 19 commits Later nightly drafts stay on `nightly`, so no pages had to be removed. No `nightly-draft/*` PRs are open. ## What changed - **Runner by default:** new Claude, Codex, OpenCode and Pi agents start on Paperclip Runner on supported hosts, with **Legacy runner** and **Upgrade runner**. - **Workspaces:** cleanup of finished workspaces, optional Git expiration, and restore points for unsaved work. Restore points are off by default. - **New pages:** Prompt injection prevention, Google Workspace, GitHub Copilot, Speko, Braintrust, Daytona, Ditto and Unikraft. - **Breaking and upgrade notes:** the run history limit, Sentry run failures off by default and the DSN variables, the Docker start command for custom images, `--yes` on `instructions-file:delete`, and slower migrations on large instances. - **Also covered:** project repositories as skill sources, roster bulk edit, Artifacts V1 (experimental, off by default), composer dismissal, `expectedStatusVersion`, `unexecuted_review_stage`, and plugin workspace providers. - **Changelog:** a v2026.1106.0 entry in `reference/changelog.md`. ## Older text corrected These were wrong at the tag, and most are also wrong on the live site: - which permissions let an agent read a peer's configuration or change instructions (`api/agents.md`) - `decideNowCount`, which doesn't exist; the field is `deskBadgeCount` - `file-resources` routes, which are board-only - the **Create project** dialog fields, a CEO rule the code doesn't enforce, and where a terminated agent's reports appear - `instructions-file:put` and `:delete` examples that always failed (`cli/agent.md`) - a curl example that returned `422` (`api/cases.md`) - Google Workspace **Reconnect** instructions, which claimed it reopens the service picker - the `permissionKey` table, which listed 8 of 21 keys - drafting text at the end of `api/agents.md` ## ⚠ Please check these - **Product behaviour that may be a parent bug.** The docs now describe the tag's code, which you may prefer to fix upstream: - The project **Environment** dropdown saves a choice, but runs ignore it (`experimental/environments.md`). - `environments:manage` is granted by roles but no environment route checks it. - `suggest-changes` is documented as agent-only, because only agents have a consent path. Company skill policy decides skill edits. - **Reader-visible mismatches in the parent UI.** The docs follow the code. Upstream copy still mentions a "Built-in agents tab", says Copilot "awaits qualification", and tells people to "Reconnect Google Workspace to change access". ## ⚠ Post-tag leaks removed Nothing to remove from an already-drafted page: post-tag surfaces such as 1Password, Vercel, Supabase deploy, custom gateway onboarding and Artifacts V1 as default never came onto this branch. Authors left out post-tag hunks of the next nightly draft, and the reasons are in the run notes. ## ⚠ Drift None. Zero findings at the tag, from a full parent snapshot. ## ⚠ Verification Failures The tag-accuracy gate reports one leak and nine review entries. None is a real failure: - **Leak:** `reference/cli/service.md`, `paperclipai payload and`. This is a false positive; it's prose from a real message at `cli/src/commands/service.ts:184`. - **Review, 8 new connector pages:** the gate can't confirm new pages. Reviewers confirmed each surface exists at the tag. - **Review, `local_tools`:** an example value from the tag's Runner README. Not provable from code, and kept deliberately: - `sandbox-providers.md` uses `sandbox.yaml`. The tag's README says `install.yaml`, which returned 404 when checked. The upstream fix is post-tag. - The Google Workspace row about older OAuth brokers rests on release notes and a design doc. The broker isn't in this repo. - External claims about provider behaviour (for example Braintrust, Daytona, Unikraft and Google scopes). ## ↻ Renames detected None. The rename helper wasn't run: the 19-commit delta adds no new adapter, skill, or plugin directories that it would check. ## Verification All checks read a checkout pinned to the tag. - **First round:** authors, a release-notes audit, an audit of corrections stranded on `nightly`, an audit of 321 lines the last realign dropped from `main` (about 130 checked directly in code), and six fresh verifiers. - **Second round:** seven new verifiers re-checked every changed area, tracing behaviour rather than matching labels, and fixed about 50 more defects. That volume means more may remain. - **Limits of that second round:** - Each verifier reported what it only string-matched. That includes parts of Artifacts V1, the **Upgrade runner** notice, Copilot run behaviour, and some Plugin SDK contract text. - The second-round fixes themselves weren't reviewed by a third round. - **Gates:** `docs:build`, `docs:test` and `sync:check` pass. - **Nothing was run against a live instance.** All of this comes from reading code. ## Screenshots **196 of 278 screenshots are stale and none were recaptured.** The list is in `SCREENSHOTS_PENDING.md`. Some visibly differ from the text, such as the removed **Run with provider trace** button and the old roster tabs. ## After merge 1. Keep the PR title as is: `tag-docs-release.yml` reads the version from it. 2. Confirm the `docs/v2026.1106.0` tag exists. 3. Run `node scripts/sync/realign-nightly.mjs release/v2026.1106.0 --push`, then audit for dropped lines and duplicated paragraphs, and set `nightly` state back to `branch_mode: nightly`. 4. Check that `docs.paperclip.ing` serves the release: a new page, a new claim, and the changelog's top entry. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Dotta <[email protected]> Co-authored-by: ClaudeCoder <[email protected]>
12 KiB
paperclip_version: v2026.1106.0 seo_title: GitHub Connector seo_description: Two separate GitHub setups: repository tools for agents, or people working with an agent from issues. Includes the shell Git and gh exception.
GitHub
GitHub supports repository tools, GitHub Copilot model access, and an experimental chat/review bot in Paperclip. Repository tools and Copilot share the GitHub entry on the Connectors page: the row's main button (Connect or Add key) for repositories, and Connect Copilot for Copilot. The bot is its own entry, GitHub Code Review Bot. Choose the one for the work you want to do.
Which do you want?
| If you want | Set up | What it gives you |
|---|---|---|
| Agents to read and act on repositories as part of their own work | GitHub → Connect or Add key | GitHub actions an agent can call, and for a managed identity the credential the run's shell uses |
| Agents to run on your GitHub Copilot plan | GitHub → Connect Copilot | An AI connection holding a Copilot token. It gives model access only, no repository access. See GitHub Copilot |
| People to start work from GitHub, or an agent to review PRs | GitHub Code Review Bot | A bot App assigned to one agent, with task-bound review tools and PR checks when enabled |
A personal GitHub connection does not create a bot App. Use GitHub connector setup for regular repository tools, or Set up a GitHub review bot for the experimental chat journey. Read Understanding GitHub PR review bots to distinguish installation, triggers, and merge requirements.
Before you give an agent a GitHub identity, read the shell exception — it is the boundary most often misread.
The shell exception
Paperclip's per-action Allowed / Ask first / Off switches govern tool calls that go through Paperclip's tool gateway. When a GitHub connection is bound to an agent as a dedicated identity, that same identity is also handed to the agent's workspace shell, and shell commands do not go through the gateway.
Paperclip states this when you change a GitHub permission:
Danger: Shell Git and
ghuse this account for the run and are not constrained by per-tool Ask-first controls.
Three things this does not mean:
- It is not a claim about other connectors, in either direction. This warning is about shell Git and
ghon this connection. It says nothing about how any other connector behaves, and you should not read it as a promise that everything else is confined to the gateway — model-provider connections supply a credential rather than making tool calls at all, and messaging channels carry conversation over their own transport. How connector access works sets out which controls apply to which kind of connection. - It is not a claim that the agent is unrestricted. The ceiling is whatever the GitHub account can do: the repositories selected on the installation, and that account's permissions on them. Narrow the account, not the switches.
- Human approval is not code review. An approved Ask first call means a person said yes to one API call. A pull request review is a separate control, on GitHub, done by a reviewer. Neither substitutes for the other.
The practical consequence: for an agent that will push code, the limits that matter are GitHub-side — selected repositories, branch protection, required reviews — not Paperclip's per-tool switches.
GitHub as an agent tool
Choose a credential
| Path | When to use it | Availability |
|---|---|---|
| Connect GitHub | The default. Paperclip manages the GitHub App authorization, and the identity is also available to shell Git and gh |
Only when the instance is enrolled with Paperclip Cloud and Cloud advertises the GitHub connector profile |
| Personal access token (advanced) | No Cloud enrollment, or you want a token you control directly | Always |
The two are not equivalent. A fine-grained personal access token carries the permissions you select on the token. The managed path's permissions come from the GitHub App registration and the repositories chosen on the installation — GitHub returns no OAuth scope list for it, so there is no scope string to inspect. If you need to reason precisely about permissions, a fine-grained token is easier to audit; if you need a durable identity for shell work, the managed path is the one that provides it.
Choose an identity
The managed path offers personal or dedicated-agent access. Its definition does not offer an organization-shared grant:
| Setup choice | Effect |
|---|---|
| My GitHub account | "Every agent may use your GitHub when you're responsible." Choose Only agents I choose to narrow it |
| A dedicated account for an agent | "That agent always uses this account, regardless of who starts the run." Commits and comments are attributable to the agent |
A dedicated agent identity is the right choice when you want agent commits distinguishable from a person's. Creating one is a manager operation: "Only connection managers can authorize a dedicated agent identity."
Repository access
For the managed GitHub App path, repository scope is set in GitHub. The connection's identity card reflects the installation:
- Accessible GitHub repositories lists the selected repositories, or shows All current and future repositories for an org-wide installation.
- Add More Repos on GitHub and Configure access on GitHub link into GitHub's installation settings.
- Refresh access re-reads the installation after you change it there.
Prefer selected repositories for the managed App. An installation granting all current and future repositories widens as the organization grows.
For a personal access token, review the token's resource owner, selected repositories, permissions, expiry, and any organization approval in GitHub. GitHub App installation controls do not set a PAT's scope.
Actions
GitHub's hosted server supplies the action list, so Paperclip does not ship a frozen copy. Read the live list on the connection's Permissions tab and use Refresh actions after GitHub changes it.
What happens to an action GitHub adds depends on which credential path you took. On the managed path new and changed actions are held back until you turn them on. On a personal access token connection they become active under the policies already in force — so review the list after a refresh rather than assuming it can only narrow. Set action permissions has the full rule.
Actions are classified read, write, or destructive and can be set Allowed, Ask first, or Off — remembering what those settings do and do not bound. See Set action permissions.
Try it
Use a read against a repository you expect the selected credential to reach:
Read the README in YOUR_ORG/YOUR_REPO and report its first heading. Do not change anything.
Compare the heading with the repository and inspect the task's connector call. For managed access, also check the GitHub App installation's selected repositories; for a PAT, check the token's repository selection and permissions. One successful read does not prove the credential cannot reach other repositories. Do not verify with a push, pull request, or merge.
Note: Illustrative task, not a recorded test result.
GitHub as a channel
People comment in an issue or pull request, mentioning the agent, and Paperclip creates a task.
Before you connect
- GitHub review bots must be switched on for the instance. It is its own experimental setting, off by default and independent of Chat connectors, enabled by an instance administrator under experimental settings.
- Permission to create a GitHub App in the organization, and to install it.
- The agent that will answer.
Set up the bot
Set up a GitHub review bot walks through the experimental setup with a Storybook example. Setup is two steps — Choose agent and Connect GitHub — after which GitHub asks you to approve creating and installing the App. Paperclip then imports the repositories you granted, waits for signed webhook delivery, links your account, and opens the bot's settings. You can also connect an App you already have.
The bot's own App supplies the assigned agent's governed GitHub tools. Check anything listed under Before your first review when setup finishes; a working webhook alone does not prove the agent can run. Your personal connection links your identity and does not replace the bot's App credentials. Workspace shell Git access is configured separately.
Access
Provider channel or repository access determines where a message can reach the integration; it does not by itself authorize agent work. Paperclip also checks the sender's linked identity and company membership. Linked users must be active non-viewer members. Unlinked senders depend on the connection's Allow unlinked people setting and any sponsor requirements. Review these controls before inviting people to use the agent.
Try it
- In a repository where the App is installed, open a scratch issue.
- Comment, mentioning the agent, and ask it to confirm it is connected.
- Expect a reply comment and a matching task in Paperclip.
Note: Procedure, not a recorded test result. Use a scratch repository or issue.
Not the same as the workspace git setup
Connect an agent to a GitHub repo is a different job: pointing a project workspace at a remote, and matching Paperclip's review stage to GitHub's. That page remains the right one for the git and gh workflow itself. This connector is how the credential gets there. Use both.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Connect GitHub is not offered | The instance is not enrolled with Paperclip Cloud, or Cloud is not advertising the GitHub profile | Use Personal access token (advanced) |
| GitHub Code Review Bot is not listed | GitHub review bots is off for the instance | Ask an administrator to enable it |
| The agent sees fewer repositories than expected | The installation does not include them | Add More Repos on GitHub, then Refresh access |
| "You don't have permission to reconnect this identity." | The identity belongs to another person or agent | Ask its owner, or use your own |
Tool calls succeed but shell git push fails |
The account's repository permissions, or branch protection | Check both on GitHub |
| Comments do not create tasks | The App is not installed on that repository, or the events are not selected | Install it there and confirm the two comment events |
| Webhook deliveries fail in GitHub | The webhook secret or URL does not match | Regenerate the secret in Paperclip and update the App |
| Needs attention | The token expired or the installation was removed | Select Reconnect |
Limitations
The managed repository-tool path depends on Cloud enrollment. The review-bot path depends on the experimental GitHub review bots setting and uses its own App. Both require appropriate GitHub repository access; review bots also have an enabled-repository subset in Paperclip. Paperclip cannot constrain shell Git or gh with per-action settings.
Related guides
-
GitHub Copilot — run agents on your Copilot plan.
-
Slack — the other mixed-purpose connector.