Skip to content

Commit 06dc22b

Browse files
jamesadevinegithub-actions[bot]Copilot
authored
docs: fix documentation drift — permissions.write incorrectly documented as required (#897)
- Fix README: remove false claim that compilation fails without permissions.write for write safe outputs. The executor always has write access via $(System.AccessToken); permissions.write only overrides the default with an ARM-minted credential. - Fix README: correct the Permission Combinations table. Both the 'Only read' and 'Neither (default)' rows incorrectly showed safe outputs cannot write. All rows can write; the difference is which token is used (System.AccessToken vs ARM-minted). - Fix README: add missing 'execution-context' field to the Front Matter Fields table. This field exists in the FrontMatter struct and has its own docs page but was absent from the table. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 9f9b112 commit 06dc22b

1 file changed

Lines changed: 11 additions & 11 deletions

File tree

README.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -204,22 +204,21 @@ sees.
204204
write: ado-agent-write
205205
```
206206
207-
> [!IMPORTANT]
208-
> If you configure any safe output that requires write access (e.g.
209-
> `create-pull-request`, `create-work-item`, `add-pr-comment`, `queue-build`,
210-
> `upload-pipeline-artifact`, and others — see the [Safe Outputs](#safe-outputs)
211-
> table for the full list) but omit `permissions.write`, compilation will fail
212-
> with a clear error. This is a safety check — write operations must always
213-
> have an explicitly configured credential.
207+
> [!NOTE]
208+
> `permissions.write` is **optional**. The Stage 3 executor always has a
209+
> write-capable token available via `$(System.AccessToken)` (the pipeline's
210+
> built-in OAuth token, running as *Project Collection Build Service*). Configure
211+
> `permissions.write` only when you need cross-org writes or named-identity
212+
> attribution — it overrides the default token with an ARM-minted credential.
214213

215214
#### Permission Combinations
216215

217216
| Configuration | Agent can read ADO? | Safe outputs can write? |
218217
|---|---|---|
219-
| Both `read` + `write` | ✅ | ✅ |
220-
| Only `read` | ✅ | |
221-
| Only `write` | ❌ | ✅ |
222-
| Neither (default) | ❌ | |
218+
| Both `read` + `write` | ✅ | ✅ (via ARM-minted token) |
219+
| Only `read` | ✅ | ✅ (via `$(System.AccessToken)`) |
220+
| Only `write` | ❌ | ✅ (via ARM-minted token) |
221+
| Neither (default) | ❌ | ✅ (via `$(System.AccessToken)`) |
223222

224223
### Step 4: Authorize the Pipeline
225224

@@ -255,6 +254,7 @@ the service connections. Approve the permissions and the pipeline is ready.
255254
| `network` | object | — | Additional allowed/blocked hosts |
256255
| `inlined-imports` | boolean | `false` | When `true`, resolves all `{{#runtime-import …}}` markers at compile time; the generated YAML is self-contained but prompt-body edits require recompilation. See [runtime-imports.md](docs/runtime-imports.md). |
257256
| `env` | map | — | Workflow-level environment variables (reserved, not yet implemented) |
257+
| `execution-context` | object | — | Configuration for the always-on execution-context plugin (PR context precompute). See [execution-context.md](docs/execution-context.md). |
258258

259259
### Markdown Body
260260

0 commit comments

Comments
 (0)