From d20c7a5bc438cb2936769844db735a8825f61190 Mon Sep 17 00:00:00 2001 From: Andrew Grimberg Date: Wed, 22 Jul 2026 06:23:36 -0700 Subject: [PATCH] Docs: Add administration permissions/events guide Document the GitHub App permissions and event subscriptions that operators must keep enabled, including the GitHub UI display names for webhook events. Also describe how to apply changes to an already-running app, including manual settings sync and the re-approval nuance for permission changes. This addresses enablement confusion from #289, #290, and #292. Clarify permission scopes, adding-permission re-approval, and the organization-owned app settings path. Signed-off-by: Andrew Grimberg Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 + docs/administration.md | 87 ++++++++++++++++++++++++++++++++++++++++++ docs/deploy.md | 2 + 3 files changed, 91 insertions(+) create mode 100644 docs/administration.md diff --git a/README.md b/README.md index 5531f94..4491fb6 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ you want to enforce the DCO on all commits. See [docs/deploy.md](docs/deploy.md) if you would like to run your own instance of this plugin. +See [administration](docs/administration.md) for the permissions and events an +existing deployment must enable. ## Modes of operations diff --git a/docs/administration.md b/docs/administration.md new file mode 100644 index 0000000..97cc821 --- /dev/null +++ b/docs/administration.md @@ -0,0 +1,87 @@ + + +# Administration + +Use this guide when you run your own DCO GitHub App instance or administer the +GitHub App that serves it. The [`app.yml`](../app.yml) manifest remains the +source of truth for required permissions and event subscriptions, but GitHub +reads it when someone creates a new app from the manifest. Later manifest edits +do not change existing app settings. + +## Required permissions + +Configure these permissions for the GitHub App. GitHub lists repository-scoped +entries under **Repository permissions** and lists **Members** under +**Organization permissions**. + + + +| Permission | Scope | Access | Why it's needed | +| --- | --- | --- | --- | +| Checks | Repository | Write | Creates the `DCO` check run and handles the manual "Set DCO to pass" check-run action. | +| Contents | Repository | Read | Reads commits with `compareCommits` so the app can check sign-offs. | +| Metadata | Repository | Read | Required baseline permission for all GitHub Apps. | +| Pull requests | Repository | Read | Reads pull request details and handles pull-request, review, review-comment, and merge-queue events. | +| Members | Organization | Read | Checks organization membership when a repository sets `require.members: false` to skip sign-off for organization members. | + + + +## Required event subscriptions + +In GitHub's "Subscribe to events" list, use the display label shown in the +second column. The technical event name appears in webhook deliveries and in +`app.yml`. + + + +| Webhook event | GitHub UI label | Gating permission | Purpose | +| --- | --- | --- | --- | +| `check_run` | Check run | Checks | Handles re-runs and the manual check-run action. | +| `pull_request` | Pull request | Pull requests | Runs the DCO check when a pull request opens or synchronizes. | +| `pull_request_review` | Pull request review | Pull requests | Re-runs DCO when a review summary contains `@dcoapp recheck` on its own line. | +| `pull_request_review_comment` | Pull request review comment | Pull requests | Re-runs DCO when an inline review comment contains `@dcoapp recheck` on its own line. | +| `push` | Push | Contents | Listed in the manifest; the current code has no dedicated `push` handler. | +| `merge_group` | Merge queue entry | Pull requests | Runs DCO on merge-queue entries. GitHub shows this event as "Merge queue entry", not `merge_group`. | + + + +## Applying changes to an already-running app + +Changing [`app.yml`](../app.yml) does not update existing app settings. For an +existing deployment, update the GitHub App settings manually: + +1. Sign in as the GitHub App owner. +1. Open the app's **Permissions & events** page: + - Personal account: **Settings** > **Developer settings** > + **GitHub Apps** > **[app]** > **Permissions & events** + - Organization: **Your organizations** > **[org]** > **Settings** > + **Developer settings** > **GitHub Apps** > **[app]** > + **Permissions & events** +1. Update **Repository permissions**, **Organization permissions**, and the + **Subscribe to events** list. +1. Save the app. + +Permission changes and event subscription changes have different operational +effects: + +- Adding a permission prompts each installation's admin to approve the change. + The app keeps working, but GitHub holds the change for that installation + until an admin accepts it. GitHub also sends a notification. +- GitHub applies a removed permission as soon as you save it, with no + installation re-approval. +- Adding or removing an event subscription does not require installation + re-approval when the app already has the event's gating permission. +- GitHub hides an event checkbox until the app has the event's gating + permission. For example, `issue_comment` needs the **Issues** permission; + **Pull requests** alone does not expose that checkbox. Enabling + issue-comment-based commands needs a permission change and installation + re-approval. + +## Post-change verification + +After saving the app, trigger the relevant event. Then open the app's +**Advanced** settings and review **Recent Deliveries**. Confirm that GitHub sent +the expected event and that the app returned a `2xx` response. diff --git a/docs/deploy.md b/docs/deploy.md index 7efa5f7..6cac119 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -9,3 +9,5 @@ If you would like to run your own instance of this GitHub App, see the [Deployment docs](https://probot.github.io/docs/deployment/). The [`app.yml`](../app.yml) file configures all required permissions and events. +See [administration](administration.md) for the permissions and events reference +and how to apply changes to a running app.