Document Slack and Linear integration permissions#142
Conversation
Adds a 'Permissions and data access' section to both the Slack and Linear integration pages so security and procurement teams can find what scopes Oz requests without asking support. For Slack, lists the scope categories the Oz app installs with and clarifies that Oz only reads from and posts to threads it has been explicitly tagged in (not channel history). For Linear, documents Oz's actor=app installation model and the four scopes it uses (read, write, app:assignable, app:mentionable), with links to Linear's agent developer docs. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The same URL is already linked from 'app actor' a few lines above; the second link adds no new context since 'delegate' is explained inline right after. Co-Authored-By: Oz <oz-agent@warp.dev>
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds permissions and data-access sections to the Slack and Linear integration docs. The Linear section lists concrete OAuth scopes, but the Slack section still describes only broad permission categories, which leaves the main security/procurement question only partially answered.
Concerns
- The Slack permissions section should include the exact Slack OAuth scope identifiers requested by the Oz app, matching the level of specificity added for Linear.
- The new Linear delegate clarification should be reconciled with the existing trigger instructions that still describe assigning Oz like a teammate.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| ### Permissions and data access | ||
|
|
||
| When a workspace admin installs the Oz app, Slack prompts them to approve the scopes Oz needs to operate. At a high level, the Oz Slack app requests permission to: |
There was a problem hiding this comment.
|
|
||
| * `read` — Read access to issues, comments, projects, and other workspace data Oz needs to understand the task it has been given. | ||
| * `write` — Write access to create comments, post agent activities (status updates, plans, results), and attach GitHub pull requests to issues. | ||
| * `app:assignable` — Allow Oz to be assigned as the delegate on an issue. Assigning an issue to Oz sets it as the delegate, not the assignee, so the human assignee retains ownership while Oz acts on their behalf. |
There was a problem hiding this comment.
💡 [SUGGESTION] This delegate clarification conflicts with the earlier trigger instructions that say to “Assign the issue to Oz as if it were a teammate”; update that wording so readers know to assign Oz as the Linear delegate rather than replacing the human assignee.
Restructures the 'Permissions and data access' section into two sub-sections: 'Workspace and team access' and 'OAuth scopes'. The workspace-vs-team distinction is the more important answer for security reviewers: Linear apps install at the workspace level, but workspace admins can restrict which teams within the workspace the app actually has access to. Lifted that out of a buried bullet into its own subsection. The scope list now points to Linear's OAuth docs and notes that the authoritative list is what shows on the install consent screen, since the live scopes are stored in our admin OAuth provider config rather than hardcoded in the source. Co-Authored-By: Oz <oz-agent@warp.dev>
1 participant
Summary
Documents the permissions and data access model for both the Slack and Linear cloud agent integrations. Adds a new "Permissions and data access" section to each integration's page.
Why
Security and procurement teams (e.g. Octopus Energy in this Slack thread) keep asking which scopes Oz requests for Slack and Linear, and we don't currently have a page to point them to. The same answer was being repeated in support threads. Putting it in docs makes it discoverable and reduces back-and-forth.
What's covered
Slack integration (
src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx):::cautionblock reminding admins to be intentional about which channels Oz is added to, since channels may contain customer data, billing info, etc.Linear integration (
src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx)actor=app), so it appears as its own user in the workspace and requires admin installationread,write,app:assignable,app:mentionable) with brief explanations of what each one enables:::cautionabout being intentional about team accessValidation
npm run buildpasses locally:::cautioncallouts, sentence case headers, and bold key termsConversation: https://staging.warp.dev/conversation/3ffab46c-2e08-4591-9fcb-f77fce0f8309
Run: https://oz.staging.warp.dev/runs/019e65b1-06b6-7bd7-b11d-173ad00339d5
This PR was generated with Oz.