docs: prototype permissions reference for factory integrations

src/content/docs/factories/integrations/github.mdx

@@ -126,6 +126,35 @@ Branches and pull requests the factory creates follow the repository's normal ru
 
 Runs authenticate with the GitHub App installation. Its repositories and permissions control access; [automation filters](/factories/automations/) only control when work starts.
 
+The [Warp Factories GitHub App](https://github.com/apps/warp-factories) requests the following permissions. Repository permissions apply to the repositories covered by the installation. A run doesn't necessarily use every grant.
+
+| Repository permission | Level | Granted access and use | Boundary |
+| --- | --- | --- | --- |
+| Actions (`actions`) | Write | Read CI logs and artifacts, and manage workflow runs | Broader than receiving workflow-completion events |
+| Administration (`administration`) | Read | Inspect repository settings, collaborators, and rules | Doesn't grant permission to change repository settings |
+| Checks (`checks`) | Write | Read check results and publish factory-definition checks | Separate from commit statuses |
+| Code scanning alerts (`security_events`) | Read | Inspect code-scanning findings for security work | Doesn't grant permission to change alerts |
+| Commit statuses (`statuses`) | Read | Inspect CI status on commits | Doesn't grant permission to publish commit statuses |
+| Contents (`contents`) | Write | Read code and create branches, commits, and repository changes | Repository rules and branch protection still apply |
+| Dependabot alerts (`vulnerability_alerts`) | Read | Inspect dependency vulnerability alerts for security work | Doesn't grant permission to change alerts |
+| Issues (`issues`) | Write | Read and update issues, comments, labels, and assignments | Broader than the issues matched by a trigger |
+| Metadata (`metadata`) | Read | Read basic repository information | Required by GitHub for installed apps |
+| Pull requests (`pull_requests`) | Write | Open and update pull requests, and post reviews and review comments | Required reviews and merge rules still apply |
+| Workflows (`workflows`) | Write | Update GitHub Actions workflow files | Separate from managing workflow runs |
+
+The app also requests permissions outside the repository:
+
+| Permission | Level | Granted access and use | Boundary |
+| --- | --- | --- | --- |
+| Organization members (`members`) | Read | Read organization membership, including checking an installer's organization role | Doesn't grant permission to manage membership |
+| Account email addresses (`emails`) | Read | Read a connected user's email addresses for account identification | Requires user authorization; isn't an installation-token grant |
+
+At installation, choose **All repositories** or **Only select repositories** to control repository access. Connecting a person's GitHub account is separate from installing the app. Repository selection doesn't narrow the organization or account permissions above.
+
+For example, a filter that starts work only on `main` doesn't restrict the installation token to `main`. Repository rules, including branch protection, still apply.
+
+To narrow access or uninstall the app, manage the installation in [GitHub's installation settings](https://github.com/settings/installations). Removing a trigger stops that route into the factory; it doesn't revoke the app's credentials.
+
 See [GitHub permissions and identity](/platform/integrations/github/#permissions-and-identity) for the full credential model.
 
 ## Factory-definition pull request checks
@@ -170,5 +199,6 @@ The check runs only for factories whose [definition is managed as code](/factori
 
 ## Related pages
 
+* [Permissions for factory integrations](/factories/integrations/permissions/) - Compare grants and review status across providers
 * [Factory automations](/factories/automations/) - Configure event matching
 * [Factory troubleshooting](/factories/troubleshooting/#work-isnt-starting) - Diagnose events that don't start work

src/content/docs/factories/integrations/gitlab.mdx

@@ -20,7 +20,7 @@ When you connect a factory to GitLab, project activity starts work in your facto
 
 Warp manages GitLab access through service accounts it creates in your connected group rather than a marketplace app:
 
-* **One manager account per workspace** - Created when you connect the group and granted the Owner role on it. Warp uses it to provision factory accounts, mint their run credentials, and maintain the group webhook; its provisioning token is valid for one year.
+* **One manager account per workspace** - Created when you connect the group and granted the Owner role on it. Warp uses it to provision factory accounts, mint their run credentials, and maintain the group webhook.
 * **One bot account per factory** - Each factory gets its own service account, named from the factory's alias plus a `-warp-` suffix and a short unique ID (for example, `acme-support-warp-01k2x3y4z5`). The bot holds the Developer role on exactly the projects you select for the factory. It is the factory's identity on GitLab. Runs authenticate as the bot, and its username is the handle you mention.
 
 The connected group's webhook delivers merge request and comment events to Warp, and matching automations turn them into factory work.
@@ -92,13 +92,28 @@ The factory never merges or approves a merge request; those decisions stay with
 
 ## Permissions
 
-Runs authenticate as the factory's bot account, not as the person whose activity triggered them:
+GitLab setup uses your OAuth authorization to provision service accounts. Factory runs then use the factory bot's credentials, not your OAuth token. Token scopes and GitLab membership roles are separate controls.
 
-* **The bot's project membership decides what runs can reach.** Each run gets a short-lived token scoped to the bot's Developer role on the factory's selected projects. Selecting projects for a factory or tightening automation filters changes when work starts, not what a running agent can access. To change access, change the factory's projects.
+Warp requires `api` and `read_user` on your setup authorization. The service-account scopes and roles below are assigned during provisioning. Review GitLab's consent screen for the complete set requested by the setup application.
+
+{/* VERIFY: Confirm whether the production GitLab OAuth authorization requests scopes beyond the required api and read_user; the persisted provider scope list and authorization parameters are not available in this checkout. */}
+
+| Permission or scope | Granted access | Function in Warp | Boundary |
+| --- | --- | --- | --- |
+| `api` on the connecting user's OAuth grant | Full API read and write access within that user's GitLab authority | Discover groups and projects, and provision the manager account | Not limited to the projects later selected for a factory |
+| `read_user` on the OAuth grant | Read the authenticated user's profile | Identify the connected GitLab user | A profile scope, not a project role |
+| `api` on the manager token; Owner role on the connected group | Group-wide API authority under the manager's role | Provision factory accounts and their tokens, and maintain the group webhook | Broader than a factory bot's selected-project access; the provisioning token expires after one year |
+| `api` on factory bot tokens; Developer role on selected projects | API read and write access under the bot's project memberships | Read code, push branches, and create merge requests, notes, and reviews | Protected-branch and project rules still apply; token expiry is date-granular, about 24 to 48 hours after minting |
+
+GitLab's [`api` scope](https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications) is broader than Git operations alone.
+
+* **The bot's project membership decides what runs can reach.** Change the factory's selected projects to change that membership. A trigger's project filter only changes when work starts; it doesn't narrow a run's credentials.
 * **Anyone who can create matching activity can start work.** The commenter doesn't need to be a Warp team member. Use project, action, and base-branch filters to control what starts runs.
 
 Disconnecting GitLab from the workspace retires the manager and every factory bot it provisioned.
 
+Revoking your personal [GitLab OAuth authorization](https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications) is separate from retiring those service accounts. Review both the connection and service-account access when withdrawing approval.
+
 ## Definitions as code
 
 If the factory's [definition is managed as code](/factories/factory-as-code/), declare GitLab triggers in an automation file:
@@ -142,4 +157,7 @@ Confirm the target project is one of the factory's selected projects and the ope
 
 Only top-level groups you own appear, and a group already connected to another Warp workspace can't be connected again. If you don't own the group, ask an owner to establish the connection in Warp.
 
-For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/).
+## Related pages
+
+* [Permissions for factory integrations](/factories/integrations/permissions/) - Compare grants and review status across providers
+* [Connect your factory](/factories/connect-your-factory/)

src/content/docs/factories/integrations/jira.mdx

@@ -81,13 +81,30 @@ When the run finishes, the result appears in the agent session. The agent doesn'
 
 ## Permissions
 
+Jira requests Forge scopes at installation, separately from linking your account to Warp.
+
+The [Warp Marketplace listing](https://marketplace.atlassian.com/apps/2476990014/warp?hosting=cloud&tab=privacy-and-security) declares the following permissions. A site's installed app version and Jira access rules determine its effective access.
+
+| Scope | Granted access | Function in Warp | Boundary |
+| --- | --- | --- | --- |
+| `read:jira-work` | Read project and issue data, including associated objects | Read work item context, comments, and workflow information | Declared for offline user impersonation; the user's Jira access still applies |
+| `read:jira-user` | Read accessible user profiles, including email addresses and avatars | Identify users and retrieve user context | Declared for offline user impersonation; not permission to manage users |
+| `write:jira-work` | Create, edit, and delete issues, post comments, and create worklogs | Update work items, comments, labels, assignments, and status | The provider grant is broader than the actions described for a run |
+| `read:permission:jira` | Read Jira permissions | Check the requesting user's project and issue permissions before writes | Doesn't grant the permissions being inspected |
+| `read:app-system-token` | Let Forge supply an app system token to the remote backend | Make Jira calls as the app bot | Separate from a human user's token |
+| `read:app-user-token` | Let Forge supply the viewing user's token to the remote backend | Verify the account being linked during setup | Separate from site-wide app installation |
+
+[Jira scopes](https://developer.atlassian.com/platform/forge/manifest-reference/scopes-product-jira/) don't override Jira permissions or issue-security rules.
+
 * **A connected Jira user becomes the run's creator, not its agent** - [Connect your Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) so a session you start is attributed to you; an unconnected account gets a prompt to connect instead of a run starting. Either way, the run executes as the agent selected by the automation, not as that Jira user.
 * **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Repository access comes from the factory itself.
 
 :::caution
 Warp's built-in Jira tools read Jira as the person who created the run; that person must link their Atlassian account to Warp in Jira under **profile** > **Personal settings** > **Warp**. To interact with Jira in runs without a human creator, such as scheduled runs or runs created by a service account or API key, add the Atlassian MCP server as a [managed MCP install](/platform/mcp/) instead.
 :::
 
+To withdraw the app's site access, a site admin manages or uninstalls it in [Atlassian's connected-app administration](https://support.atlassian.com/organization-administration/docs/managing-an-installed-app/). Removing a factory automation or unlinking a personal account is not the same as uninstalling the Jira app.
+
 ## Troubleshooting
 
 * **Warp is unavailable in Jira** - Confirm the Warp app is installed on the Jira Cloud site. On the app's **Configure** page, click **Connect to Warp** if the installation isn't connected to a workspace. If someone else is completing setup, confirm that their setup link is still active.
@@ -98,5 +115,6 @@ Warp's built-in Jira tools read Jira as the person who created the run; that per
 
 ## Related pages
 
+* [Permissions for factory integrations](/factories/integrations/permissions/) - Compare grants and review status across providers
 * [Connect your factory](/factories/connect-your-factory/)
 * [Factory troubleshooting](/factories/troubleshooting/#work-isnt-starting)

src/content/docs/factories/integrations/linear.mdx

@@ -20,6 +20,25 @@ When the factory needs an answer, reply in Linear, or open the live run to steer
 
 For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/).
 
+## Permissions
+
+Linear app authorization is separate from linking a teammate's Warp account. In Linear's `actor=app` authorization model, a workspace admin installs the app, and updates are attributed to the app rather than the installer.
+
+The table describes the scopes in Warp's development configuration. The production authorization request hasn't been confirmed; review Linear's consent screen before approving workspace access.
+
+{/* VERIFY: Confirm the production Linear OAuth scope list and actor parameter from the persisted provider record or a live authorization URL; the public directory listing exposes neither, and Warp login blocks the connection flow. */}
+
+| Scope to confirm | Granted access | Function in Warp | Boundary |
+| --- | --- | --- | --- |
+| `app:assignable` | Let the app be delegated issues and made a project member | Delegate work to the factory | Doesn't grant repository access |
+| `app:mentionable` | Let the app be mentioned in issues, documents, and other editor surfaces | Start an agent session with a mention | Not itself a grant to edit those resources |
+| `comments:create` | Create issue comments | Acknowledge requests and post results | Narrower than the separately listed `write` scope |
+| `issues:create` | Create and update issues, and create their attachments | Create or update tracked work | Despite its name, this scope isn't create-only |
+| `read` | Read data available to the app | Retrieve issue context and workspace metadata | Subject to the app's team access in Linear |
+| `write` | Broad write access available to the app | Update issues, workflow state, and delegation | Broader than comment creation; trigger filters don't narrow this grant |
+
+These scope meanings follow [Linear's OAuth reference](https://linear.app/developers/oauth-2-0-authentication) and [app authentication model](https://linear.app/developers/agents#actor-and-scopes). A workspace admin can change or revoke the app's team access in Linear. Selecting teams for a factory's automations controls routing, not the underlying OAuth grant.
+
 ## Connect Linear
 
 You connect Linear either while creating a factory, at the **Connect your issue trackers** step, or afterward from the factory's **Settings**. Either way you do the same two things:
@@ -84,3 +103,8 @@ Connecting Linear doesn't grant repository access. Branches and pull requests us
 * **An event doesn't start work** - Confirm the automation is enabled, the event type matches, and every filter matches the issue's current values or the state change.
 * **One action starts multiple runs** - Look for overlapping agent-session and comment triggers, then narrow or remove one.
 * **No pull request appears** - Check the factory's code-host credentials and repository access. Linear authorization alone doesn't allow code changes.
+
+## Related pages
+
+* [Permissions for factory integrations](/factories/integrations/permissions/) - Compare grants and review status across providers
+* [Linear integration](/platform/integrations/linear/) - Install or remove the workspace app