Skip to content

Commit 38969ae

Browse files
Merge branch 'main' into fix/lockdown-bot-permission-check
2 parents 5290868 + df32d7e commit 38969ae

11 files changed

Lines changed: 1924 additions & 0 deletions

‎docs/feature-flags.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,64 @@ Get, create, and update return an `artifact` object. List returns a `list` objec
146146
containing `artifacts`, `page`, and `perPage`; delete returns a `deleted` object
147147
containing `issue_number`, `artifact_number`, and a confirmation message.
148148

149+
### Pull request artifacts
150+
151+
Enable `--features=pull_request_artifacts` (or
152+
`GITHUB_FEATURES=pull_request_artifacts`) to expose
153+
`pull_request_artifact_read` (`method: list`) and
154+
`pull_request_artifact_write` (`method: upsert | delete`) in the
155+
`pull_requests` toolset. This flag is **off by default**, including in Insiders
156+
mode. Read-only mode exposes only the read tool. Both tools reject calls in
157+
lockdown mode.
158+
159+
All operations require `owner`, `repo`, and `pull_number`. The tools resolve
160+
the repository's numeric ID and use the configured authenticated GitHub
161+
client and API base URL. They declare `repo` in OAuth challenge metadata;
162+
the API separately enforces pull request read access for list and artifact
163+
write access for upsert/delete, including repository writeability and storage
164+
availability. No endpoint-specific preview header is added.
165+
166+
Upsert and delete address artifacts by **name**, not artifact number or global
167+
ID. Supply exactly one of `name` (the exact original name) or `name_key` (the
168+
lossless key returned by reads and writes). Returned `name` values are sanitized
169+
for display and must not be used as mutation keys: distinct original names can
170+
have the same display name. Pass `name_key` verbatim to update or delete an
171+
artifact discovered through a read. Keys use unpadded URL-safe Base64 encoding
172+
of the original name and are not authorization tokens.
173+
Upsert requires `body` and optionally accepts `commit_oid`.
174+
The body is sent unchanged, including an empty string; the API validates its
175+
content and constraints. Upsert accepts both creation (201) and replacement
176+
(200) responses. Delete rejects `body` and `commit_oid`.
177+
Before deletion, the client must obtain explicit user confirmation of the exact
178+
repository, PR number, and artifact name through form elicitation. Confirmation
179+
requires MCP protocol `2026-07-28` or later and configured request-state protection.
180+
The protected state binds approval to the target repository ID, PR, and artifact
181+
name and expires after ten minutes. Missing, invalid, expired, declined, or
182+
canceled confirmation prevents deletion, as does a changed repository identity.
183+
Clients without the required protocol or form-elicitation support cannot delete;
184+
list and upsert remain available. This relies on the client to present the
185+
confirmation to the user rather than answer on the model's behalf.
186+
Writes are not automatically retried; API errors, including conflicts,
187+
validation failures, throttling, and storage failures, are returned explicitly.
188+
189+
List includes artifact bodies and accepts `commit_oid`: omit it or use
190+
`current` for the PR's current head, use `all` for every commit, or supply an
191+
explicit commit OID. For a stable commit selection across pages, use an
192+
explicit OID instead of a moving PR head. List returns one requested page
193+
(`page` defaults to 1, `perPage` defaults to 30 and is limited to 100).
194+
Request `next_page` when present; its value comes from the API's REST Link
195+
header, not the number of returned artifacts.
196+
197+
Upsert returns an `artifact` object. List returns a `list` object containing
198+
`artifacts`, `page`, `perPage`, and optional `next_page`. Delete returns a
199+
`deleted` object containing `pull_number`, display `name`, lossless `name_key`,
200+
and a confirmation message.
201+
Artifact IDs are opaque JSON strings or integers and are never mutation
202+
identifiers. Results preserve nullable commit, creator, and timestamp
203+
metadata; list metadata describes the returned artifact version. Names and
204+
creator logins receive plain-text sanitization, and bodies use the existing
205+
content sanitizer, preserving HTML source while filtering invisible characters.
206+
149207
Tools, resources, and prompts use `inventory.NewFeatureRule` when feature flags
150208
change whether they are available. Each rule declares the flags it references
151209
and evaluates them with a fail-closed `FeatureResolver`, so normal Go boolean
@@ -529,6 +587,29 @@ as output formatting) won't appear here.
529587
- `repo`: Repository name (string, required)
530588
- `type`: (string, optional)
531589

590+
### `pull_request_artifacts`
591+
592+
- **pull_request_artifact_read** - Read pull request artifacts
593+
- **OAuth Challenge Scopes**: `repo`
594+
- `commit_oid`: Commit selection: omitted or current for the current PR head, all for every commit, or an explicit commit OID (string, optional)
595+
- `method`: (string, required)
596+
- `owner`: Repository owner (string, required)
597+
- `page`: Page number, starting at 1 (default 1) (integer, optional)
598+
- `perPage`: Results per page, from 1 to 100 (default 30) (integer, optional)
599+
- `pull_number`: Positive pull request number (integer, required)
600+
- `repo`: Repository name (string, required)
601+
602+
- **pull_request_artifact_write** - Write pull request artifacts
603+
- **OAuth Challenge Scopes**: `repo`
604+
- `body`: Required for upsert: artifact content; an empty string is sent unchanged. Not supported for delete (string, optional)
605+
- `commit_oid`: Optional commit OID for upsert only; omission preserves the API default (string, optional)
606+
- `method`: (string, required)
607+
- `name`: Exact artifact name for creation or addressing; mutually exclusive with name_key. Do not copy sanitized display names from read results (string, optional)
608+
- `name_key`: Lossless addressing key returned by artifact reads or writes; mutually exclusive with name. Pass verbatim without decoding (string, optional)
609+
- `owner`: Repository owner (string, required)
610+
- `pull_number`: Positive pull request number (integer, required)
611+
- `repo`: Repository name (string, required)
612+
532613
### `agent_automations`
533614

534615
- **create_automation** - Create a repository automation
Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
{
2+
"annotations": {
3+
"destructiveHint": false,
4+
"idempotentHint": false,
5+
"readOnlyHint": true,
6+
"title": "Read pull request artifacts"
7+
},
8+
"description": "List GitHub pull request artifact versions including their bodies. Names are sanitized for display; use the returned name_key, not name, for subsequent writes. commit_oid defaults to the current PR head; use all or an explicit commit OID to change the selection. Returns one page; request next_page when present. Repository access and the repository's pull_request_artifacts_api rollout are enforced by GitHub. Unavailable in lockdown mode.",
9+
"icons": [
10+
{
11+
"mimeType": "image/png",
12+
"src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAACwUlEQVRIie2Vz28UZRjHP993pi0QIC3YahNjirtmd3bS3Q1eUHvQEPUiEv8A4kXjwRJ78MCFBLjBBRKCHowHE38cNCbGGx6IUoKiodtNpoNmTJp4oSJNQ3pw29l5POxus2wo3QTwxPc0887zfD7zvu9kXnjEUfdNrjj5vJOmMP4e9JrfR1G02tuQD8tvgpck0dxCPwK30ViqnJTcr4bOmfRlI/PrhUJ5313woDpDpu8ss7f6nYHrvDnGcYlPsoY/bKaXwHY3HWfvgmNnMX0zvMM7069A3c3pkEYWa7UVgFxQPSfs7SSeH3k2rEy5jMubMBoG1yQ+SBbm53of+gCybMkk/H8VAFdbZisZLAFsJ11oyL+BUURcwrjWAZixXeIwxs/5UuVAr0QAYRjubGR+HWy3mb6QCIBXQe8nce0jgIkwfMo3/xLG085x8I9ofkMyUa0O+w2rgS0mcf3lboEDiKJo1cvsIDDr4D1DhTb8407hYhTdTJW+AvrdMnuhG9Je1m9BBzbfjXbyQcXypeqJLQt7+0rVE/mgYr3j7l7FDzOPBY8FDx6vc1EolPeNjI5/Jpgw7Lm9o+Pry//c/K0PhnLFyrSMDxE79jwxvn9079gvt28vrUD7V1EoFHalbltd2C7DfS4sAF4DTSdx7cL96LliZVriPPADuL+geRh0Z8il5SiKVn2ATENvCCYw78U/b8xdBcgHlYuGHQXuK5A4ClxM4vnXW8Lqp5JdWWt6h4CvWnsgxgDSbRZ3Gg0tCJ7sY4nGwDZOt/WBZtzN9FswLgM2sGann5mcPDaw5pWEHQH7cUu86SdkR3LF6tfrA814MNVpwNrM1leUxPXrSKfMeHcwdctyNotY8c3NbMX3LJsB3ZHsymDqlkHvYHYyievXWxPpSj4o75eYIuPWZof+vRKG4c61pncIx6gZsx34/5L/ACy3ElqUYhuvAAAAAElFTkSuQmCC",
13+
"theme": "light"
14+
},
15+
{
16+
"mimeType": "image/png",
17+
"src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAABn0lEQVRIie2Vvy5EURDGvyMUkhUU/pS2Q2clwvIKqL0Cm9ArrBcQShJPoLFR2YaIhIjQ7a7E39IiCgqVn8KsPY697E3oTHPumTPf990z986M9Mfm/A0wKGlMUlnSlnPuOQQAE5LOnXOFWErAIvBK1S6BZBAzZ2fzcckHjXwVaAXSwD2wWYN8A2iKK1ABt3m+ZeDRnseIthdgDxioxd1o662tfZIO7Lnf8xcklST1StqRdORxNEualHQIDDvnTmvdIGE5vwdWgLy93bQX0w0UgSdgKMC3AdfA7ndpSgKbduUbYBoI/7Ju4BiYrYFfAl4iBbxAgOyPgV9xWYDQ3xCXKK79C/wL/KJZoeW8QpsJCy0C54AMULaGmQu7sIAW4MpaxTKwbQU3U4dAxmLzwLpxXAIJP2jKgkY8Xx4o1SFwBmx7+7RxTUnVb9Bpa9HDFiR1/SRgWH+6FT3/h2qK6sBpB0aBB7yB880NcpaWtGHXjCsVBmb5PDIvgJ46BJKW84q9AguV87Adp/Q+9O8UMfQjRBKSxiV1SNp3zp3Ug/sVewPruexhKwhGXQAAAABJRU5ErkJggg==",
18+
"theme": "dark"
19+
}
20+
],
21+
"inputSchema": {
22+
"additionalProperties": false,
23+
"properties": {
24+
"commit_oid": {
25+
"description": "Commit selection: omitted or current for the current PR head, all for every commit, or an explicit commit OID",
26+
"type": "string"
27+
},
28+
"method": {
29+
"enum": [
30+
"list"
31+
],
32+
"type": "string"
33+
},
34+
"owner": {
35+
"description": "Repository owner",
36+
"minLength": 1,
37+
"type": "string",
38+
"x-mcp-header": "owner"
39+
},
40+
"page": {
41+
"description": "Page number, starting at 1 (default 1)",
42+
"minimum": 1,
43+
"type": "integer"
44+
},
45+
"perPage": {
46+
"description": "Results per page, from 1 to 100 (default 30)",
47+
"maximum": 100,
48+
"minimum": 1,
49+
"type": "integer"
50+
},
51+
"pull_number": {
52+
"description": "Positive pull request number",
53+
"minimum": 1,
54+
"type": "integer"
55+
},
56+
"repo": {
57+
"description": "Repository name",
58+
"minLength": 1,
59+
"type": "string",
60+
"x-mcp-header": "repo"
61+
}
62+
},
63+
"required": [
64+
"owner",
65+
"repo",
66+
"pull_number",
67+
"method"
68+
],
69+
"type": "object"
70+
},
71+
"name": "pull_request_artifact_read",
72+
"outputSchema": {
73+
"additionalProperties": false,
74+
"properties": {
75+
"list": {
76+
"additionalProperties": false,
77+
"properties": {
78+
"artifacts": {
79+
"items": {
80+
"additionalProperties": false,
81+
"properties": {
82+
"body": {
83+
"type": "string"
84+
},
85+
"commit_oid": {
86+
"type": [
87+
"null",
88+
"string"
89+
]
90+
},
91+
"created_at": {
92+
"type": [
93+
"null",
94+
"string"
95+
]
96+
},
97+
"creator": {
98+
"additionalProperties": false,
99+
"properties": {
100+
"id": {
101+
"type": "integer"
102+
},
103+
"login": {
104+
"type": "string"
105+
}
106+
},
107+
"required": [
108+
"login",
109+
"id"
110+
],
111+
"type": [
112+
"null",
113+
"object"
114+
]
115+
},
116+
"id": {
117+
"description": "Opaque artifact ID; mutations use name or name_key instead",
118+
"type": [
119+
"string",
120+
"integer"
121+
]
122+
},
123+
"name": {
124+
"description": "Sanitized display name; use name_key when addressing this artifact",
125+
"type": "string"
126+
},
127+
"name_key": {
128+
"description": "Lossless base64url-encoded artifact name; pass verbatim as name_key to write operations",
129+
"type": "string"
130+
},
131+
"number": {
132+
"type": "integer"
133+
},
134+
"updated_at": {
135+
"type": [
136+
"null",
137+
"string"
138+
]
139+
}
140+
},
141+
"required": [
142+
"id",
143+
"number",
144+
"name",
145+
"name_key",
146+
"body",
147+
"commit_oid",
148+
"creator",
149+
"created_at",
150+
"updated_at"
151+
],
152+
"type": "object"
153+
},
154+
"type": [
155+
"null",
156+
"array"
157+
]
158+
},
159+
"next_page": {
160+
"description": "Next page from the API Link header; absent when there is no next page",
161+
"type": "integer"
162+
},
163+
"page": {
164+
"type": "integer"
165+
},
166+
"perPage": {
167+
"type": "integer"
168+
}
169+
},
170+
"required": [
171+
"artifacts",
172+
"page",
173+
"perPage"
174+
],
175+
"type": [
176+
"null",
177+
"object"
178+
]
179+
}
180+
},
181+
"required": [
182+
"list"
183+
],
184+
"type": [
185+
"null",
186+
"object"
187+
]
188+
}
189+
}

0 commit comments

Comments
 (0)