|
| 1 | +# GitHub Copilot For Jira Setup |
| 2 | + |
| 3 | +FieldWorks uses authenticated Jira Data Center access. Jira issues are not anonymously public, but some issues may be designated as safe for agent use through the approved service-user/API policy. |
| 4 | + |
| 5 | +The rule for this repository is: |
| 6 | + |
| 7 | +- agent access to Jira must go through the approved service user, |
| 8 | +- the service user's API scope must determine which issues are exposed, |
| 9 | +- personal Jira credentials must not be used for automated Copilot setup or workflow runs. |
| 10 | + |
| 11 | +## Repository Guidance |
| 12 | + |
| 13 | +The reusable workflow at `.github/workflows/copilot-setup-steps.yml` is intended to stay safe for Jira-triggered agent runs because it: |
| 14 | + |
| 15 | +- uses least-privilege repository permissions, |
| 16 | +- avoids installer/signing/release secrets, |
| 17 | +- allows Jira credentials only when they are supplied as part of the approved service-user setup, |
| 18 | +- requires `JIRA_URL` when Jira API credentials are present. |
| 19 | + |
| 20 | +What this workflow does not enforce: |
| 21 | + |
| 22 | +- whether an individual Jira issue is approved for agent visibility, |
| 23 | +- which Jira projects are in scope, |
| 24 | +- the service user's effective permissions. |
| 25 | + |
| 26 | +Those controls belong in the Jira-side API/service-user policy. |
| 27 | + |
| 28 | +## Required Secrets |
| 29 | + |
| 30 | +For the FieldWorks Jira Data Center setup, the normal configuration is: |
| 31 | + |
| 32 | +- `JIRA_URL` |
| 33 | +- `JIRA_PAT_TOKEN` |
| 34 | + |
| 35 | +If your integration layer uses different variable names, keep them mapped at the caller workflow or environment level and avoid changing this reusable workflow unless the contract changes. |
| 36 | + |
| 37 | +Guidance: |
| 38 | + |
| 39 | +- Prefer environment or organization secrets over ad hoc per-workflow values. |
| 40 | +- Use a dedicated service-user PAT or API token. |
| 41 | +- Do not use a personal admin token. |
| 42 | +- Scope the service account so the API only exposes issues marked for agent/public handling. |
| 43 | + |
| 44 | +## Optional Variants |
| 45 | + |
| 46 | +Other helper tooling in this repository may still support: |
| 47 | + |
| 48 | +- Jira Cloud: `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN` |
| 49 | +- Jira Data Center: `JIRA_URL`, `JIRA_PAT_TOKEN` |
| 50 | + |
| 51 | +For FieldWorks, the Data Center service-user path is the intended default. |
| 52 | + |
| 53 | +## Recommended Admin Setup |
| 54 | + |
| 55 | +1. Create a dedicated Jira service user for Copilot/agent access. |
| 56 | +2. Grant that service user only the minimum permissions needed to read issues approved for agent use. |
| 57 | +3. Enforce issue visibility through your API layer or Jira-side policy, rather than assuming anonymous public access. |
| 58 | +4. Store `JIRA_URL` and `JIRA_PAT_TOKEN` as managed secrets at the environment or organization level. |
| 59 | +5. Keep direct browsing of Jira URLs out of agent tooling unless it is going through the approved authenticated integration path. |
0 commit comments