# CI Secrets Configuration

This document describes the GitHub Actions secrets used by the
`ai-pr-loop` workflow (`.github/workflows/ai-pr-loop.yml`).

## Secrets

| Secret | Purpose | Required |
|--------|---------|----------|
| `GITHUB_TOKEN` | Default token for merge, comments, and general API calls | Yes (auto-provided) |
| `COPILOT_GITHUB_TOKEN` | Token for Copilot review requests | Yes |
| `AGDT_PR_APPROVER_PAT` | Dedicated token used only for the final PR approval from a separate identity | Yes |
| `SPECKIT_PR_TOKEN` | Dedicated token for AI PR Loop writes/dispatches/takeover attribution and audit write/dispatch/apply operations | Yes |

## `AGDT_PR_APPROVER_PAT`

### Why a separate token?

GitHub prevents a user from approving their own pull request. When the
AI PR Loop creates a PR under the `GITHUB_TOKEN` identity and then
attempts to approve it with the same token, the approval is rejected.
A Personal Access Token from a **different** GitHub account is required
so the approval comes from a distinct identity.

### Required permissions

- **Token type**: Fine-grained Personal Access Token (recommended)
- **Repository access**: Only `swai-factory/agentic-devtools`
- **Permissions**:
  - `Pull requests: Write`
- **Expiry**: 90 days (rotate before expiration)

### Setup steps

1. Sign in to the dedicated approver account (e.g., `swai-factory-pr-approver`).
2. Navigate to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**.
3. Click **Generate new token**.
4. Configure:
   - **Name**: `AGDT_PR_APPROVER_PAT`
   - **Repository access**: Only select repositories → `swai-factory/agentic-devtools`
   - **Permissions**:
     - `Pull requests: Write`
5. Copy the generated token.
6. In the repository, go to **Settings → Secrets and variables → Actions**.
7. Create a new secret named `AGDT_PR_APPROVER_PAT` with the token value.

### Rotation procedure

1. Generate a new token following the setup steps above.
2. Update the `AGDT_PR_APPROVER_PAT` secret in repository settings.
3. The old token is invalidated automatically once the new one is saved.
4. No workflow changes are required — the secret name stays the same.

### Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| `AGDT_PR_APPROVER_PAT is not configured` (warning) | Secret not set in repository | Add the secret per setup steps |
| `HTTP 401: Bad credentials` | Token expired or revoked | Rotate the token |
| `HTTP 403` | Insufficient permissions or wrong repo scope | Regenerate with correct permissions |
| Approval rejected (self-approval) | Token belongs to the same account as PR author | Use a different account's token |

## AI PR Loop + Audit Writes (`SPECKIT_PR_TOKEN`)

`SPECKIT_PR_TOKEN` is used by AI PR Loop operations that write to a PR (comments, dispatches,
checkouts using PAT auth, and takeover-attributed git writes) and by the audit
review-feedback pipeline. This keeps loop-authored actions on the `AMARSNIK_swica` identity,
while `AGDT_PR_APPROVER_PAT` remains approval-only.

It is required for AI PR Loop and audit write operations:

- PR loop dispatch/comment/check-out paths that use `GH_TOKEN`/checkout PAT auth
- takeover-attributed loop commits authored as `AMARSNIK_swica`

- creating per-batch tracking issues
- pushing prepared `audit/batch-*` branches (dispatch uses `SPECKIT_PR_TOKEN` in-URL
  because the dispatch workflow checks out with `persist-credentials: false`)
- dispatching evaluation via coding-agent assignment
- **opening the draft instruction-update PR** in `agdt-audit-apply` (PR creation uses
  `SPECKIT_PR_TOKEN` via `GH_TOKEN` so the AI PR loop / downstream `pull_request` events
  are triggered — GitHub suppresses these events for `GITHUB_TOKEN`-created PRs)

### Split-identity rationale for audit apply

The audit-apply workflow (`audit-review-feedback-apply.yml`) uses **two different identities**
for the branch push and PR creation:

| Step | Identity | Why |
|------|----------|-----|
| `git push origin` (instruction-update branch) | `GITHUB_TOKEN` (ambient) | The `apply-audit` job has `contents: write`; using the ambient token avoids embedding PAT secrets in git URLs and matches the speckit phase-progression pattern. |
| `provider.create_pull_request(...)` | `SPECKIT_PR_TOKEN` (via `GH_TOKEN`) | PRs opened with `GITHUB_TOKEN` do not trigger downstream `pull_request` events, so the AI PR loop would never fire. A PAT from a separate identity is required. |

### Required permissions

- **Token type**: Classic Personal Access Token
- **Scopes**:
  - `repo`
  - `workflow`

`COPILOT_GITHUB_TOKEN` must not be used for these writes because it is fine-grained and
does not reliably provide the required `issues:write` capability.
