From 9668845a4ced44f1ff925e19af1fc809036be8fa Mon Sep 17 00:00:00 2001 From: woywro Date: Mon, 11 May 2026 22:03:01 +0200 Subject: [PATCH] docs(jira): clarify scope vs project-permissions and drop no-op project-member step --- SETUP.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/SETUP.md b/SETUP.md index 805de87..2f6985e 100644 --- a/SETUP.md +++ b/SETUP.md @@ -55,28 +55,31 @@ ai-workflow authenticates to Jira as an **Atlassian service account** — a mach 1. Go to **https://admin.atlassian.com** → pick your organization → **Directory** → **Service accounts**. 2. **Create service account** → name it (e.g. `ai-workflow`) → grant product access to **Jira** only. -3. In Jira, add the service account (by its principal name) to the target project as a **member** or via a group. Grant exactly: browse, create, edit, transition, and comment on issues in `JIRA_PROJECT_KEY`. Nothing else. **Generate a scoped API token:** -4. Back in **admin.atlassian.com → Directory → Service accounts**, open the account you just created → **API tokens** → **Create credentials**. Give it a label (e.g. `ai-workflow-prod`) and pick these two **classic** scopes: +1. Back in **admin.atlassian.com → Directory → Service accounts**, open the account you just created → **API tokens** → **Create credentials**. Give it a label (e.g. `ai-workflow-prod`) and pick these two **classic** scopes: | Scope | Covers | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read:jira-work` | `GET /issue/{id}` (summary, description, comments, labels, status, project, attachments), `GET /issue/{id}/transitions`, `GET /search/jql`, attachment download | | `write:jira-work` | `POST /issue/{id}/comment`, `POST /issue/{id}/transitions` (move ticket) | -5. Copy the token immediately (it's shown once) → `JIRA_API_TOKEN`. +2. Copy the token immediately (it's shown once) → `JIRA_API_TOKEN`. + +> **Scope ≠ project permissions.** The token's scopes (`read:jira-work`, `write:jira-work`) gate _which API categories_ the token can call — but `write:jira-work` covers destructive endpoints like `DELETE /issue/{id}` too. The second gate is the project's **Permission Scheme** in Jira itself: the service account is a regular Jira user, and Jira filters every request by that user's permissions on the project. +> +> Concretely: leave the service account in `jira-users` (default) and make sure your project's Permission Scheme does **not** grant `Delete Issues`, `Delete All Comments`, `Delete All Attachments`, `Administer Projects`, or `Manage Sprints` to `jira-users` or `Any logged in user`. Atlassian's `Default Permission Scheme` ships this way out of the box — verify at `/secure/admin/ViewPermissionSchemes.jspa` → find `Default Permission Scheme` → click **Permissions**. A `DELETE` from the bot will then return `403 You do not have permission to delete issues in this project.` even though the token scope allows the call. If you need stricter isolation (e.g. hide the bot from other projects), create a dedicated group + dedicated scheme — otherwise the default should be sufficient. **Capture the rest of the config:** -6. Note your Atlassian instance URL (e.g. `https://your-domain.atlassian.net`) → `JIRA_BASE_URL`. -7. Open the project ai-workflow will operate on. Note its key (e.g. `AWT`) → `JIRA_PROJECT_KEY`. -8. On the project board, identify the three columns ai-workflow uses. Create them if they don't exist: +1. Note your Atlassian instance URL (e.g. `https://your-domain.atlassian.net`) → `JIRA_BASE_URL`. +2. Open the project ai-workflow will operate on. Note its key (e.g. `AWT`) → `JIRA_PROJECT_KEY`. +3. On the project board, identify the three columns ai-workflow uses. Create them if they don't exist: - `COLUMN_AI` — tickets assigned to the agent (default: `AI`) - `COLUMN_AI_REVIEW` — completed tickets pending human review (default: `AI Review`) - `COLUMN_BACKLOG` — tickets bounced back for clarification (default: `Backlog`) -9. Generate a webhook secret to authenticate Jira → Vercel deliveries: +4. Generate a webhook secret to authenticate Jira → Vercel deliveries: ```bash openssl rand -hex 32 ```