Skip to content

Commit 56613bf

Browse files
darthwillisCopilot
darthwillis
and
Copilot
committed
Fix runtime guidance pointing at a removed README section
The 403 handler in registerNamespace directed users to a "Write-only apps" section that this PR removed, so anyone hitting a permission error was sent to documentation that no longer exists. It now links to the published Selecting permissions guide. Also replaces the remaining "write-only app" phrasing with "Read and write", matching the permission level name the UI and docs use, and adds the permissions reference to the API Reference section so the per-endpoint access level is reachable from where the endpoints are listed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 97372c67-02e2-4b8b-a713-1d9e9c42f6ca
1 parent fed1104 commit 56613bf

2 files changed

Lines changed: 7 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ When the installation completes, GitHub sends an `installation.created` webhook
207207

208208
## API Reference
209209

210-
Each endpoint links to its [REST API reference](https://docs.github.com/en/rest/orgs/custom-properties) entry, which covers the request body, responses, request limits, display name rules, property name and value constraints, and cleanup behavior. The [setup guide](https://docs.github.com/en/organizations/managing-organization-settings/sync-external-custom-properties#3-create-the-automation) lists them in the order an integration typically calls them, and each has a matching helper in [`example-server/app.js`](example-server/app.js).
210+
Each endpoint links to its [REST API reference](https://docs.github.com/en/rest/orgs/custom-properties) entry, which covers the request body, responses, request limits, display name rules, property name and value constraints, and cleanup behavior. The access level and token types each one requires are listed in [Permissions required for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps#organization-permissions-for-external-custom-properties-for-repositories). The [setup guide](https://docs.github.com/en/organizations/managing-organization-settings/sync-external-custom-properties#3-create-the-automation) lists them in the order an integration typically calls them, and each has a matching helper in [`example-server/app.js`](example-server/app.js).
211211

212212
| Endpoint | Helper function |
213213
|----------|-----------------|

‎example-server/app.js‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,8 +156,9 @@ async function registerNamespace(octokit, org) {
156156
`This app installation cannot register itself in ${org} (it needs ADMIN on ` +
157157
`"External custom properties for repositories"). An org admin — or a user/token with the ` +
158158
`organization_external_properties_for_repos:admin fine-grained permission — must call the ` +
159-
`registration endpoint with this installation's installation_id (see the README, ` +
160-
`"Write-only apps"). Value writes will fail until the installation is registered.`
159+
`registration endpoint with this installation's installation_id. See ` +
160+
`https://docs.github.com/en/organizations/managing-organization-settings/sync-external-custom-properties#selecting-permissions. ` +
161+
`Value writes will fail until the installation is registered.`
161162
);
162163
return false;
163164
}
@@ -205,7 +206,7 @@ async function writeExternalCustomProperties(octokit, org, repositoryNames, prop
205206
if (isNotRegisteredError(error)) {
206207
console.warn(
207208
`Cannot write properties to ${org}: the app installation is not registered yet. ` +
208-
`Register the namespace first (or wait for an org admin to register a write-only app).`
209+
`Register the namespace first (or wait for an org admin to register an app that only has Read and write).`
209210
);
210211
return false;
211212
}
@@ -505,7 +506,8 @@ app.webhooks.onError((error) => {
505506
// --- Periodic sync ---
506507
// Re-applies properties on a schedule to catch drift or newly added repos. Assumes the
507508
// installation is already registered (from the installation.created flow, or by an org admin for
508-
// write-only apps). If it is not yet registered, writeExternalCustomProperties logs a clear message.
509+
// apps that only have Read and write). If it is not yet registered, writeExternalCustomProperties
510+
// logs a clear message.
509511

510512
async function periodicSync() {
511513
console.log(`[Sync] Running periodic sync...`);

0 commit comments

Comments
 (0)