Point README at the published docs instead of restating them - #3
Merged
Merged
Conversation
darthwillis
force-pushed
the
readme-dedupe-live-docs
branch
from
September 29, 2026 21:15
24625a5 to
dba8ccf
Compare
darthwillis
marked this pull request as ready for review
September 29, 2026 21:15
darthwillis
requested review from
isaacmbrown and
joshbanks14
and
a balanced review from Copilot
and removed request for
a team and
Copilot
September 29, 2026 21:15
isaacmbrown
approved these changes
Sep 30, 2026
isaacmbrown
left a comment
There was a problem hiding this comment.
Much cleaner, thanks for doing this! 🚀
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Removing the permissions subsection leaves a runtime error message pointing users to documentation that no longer exists.
Review effort: Balanced
Findings: 1
What changed in this PR
Refocuses the README on configuring and running the sample server while linking to authoritative GitHub Docs for platform behavior.
Changes:
- Removes duplicated conceptual and permission documentation.
- Links setup details and constraints to published documentation.
- Maps REST endpoints to sample helper functions.
| File | Description |
|---|---|
README.md |
Streamlines guidance and adds authoritative documentation links. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
darthwillis
force-pushed
the
readme-dedupe-live-docs
branch
from
September 30, 2026 16:42
56613bf to
1536cf3
Compare
The "Integrating custom properties with an external system" guide is now live on docs.github.com and covers what external custom properties are, display names and namespacing, the permission model, and installation behavior. That guide also links here as the example implementation, so this README should cover configuring and running the server rather than re-explaining the feature. Several sections restated GitHub behavior the docs now own, which meant they could drift out of sync as the feature changes: - Condensed the intro. Two of its three paragraphs duplicated the guide's lead, one restating its intro frontmatter and the other its external-properties-intro reusable, down to the same examples. - Removed "How it works: namespaces and registration" in favor of a pointer to the guide. - Collapsed "Permissions and who registers" to the choice this sample makes, linking to Selecting permissions for the full model. - Trimmed the repository-access explanation from Step 5, linking to Install the app. - Replaced the inline display name length and character rules with a link to the registration endpoint, which documents them alongside the validation errors they produce. The API Reference table previously repeated the endpoint list already in the guide. Each endpoint now links to its own REST reference anchor and is paired with the helper function in app.js that calls it, which is information only this repository can provide. Permission links point at the programmatically maintained permissions reference, which also documents the token types each endpoint accepts. Removing the "Write-only apps" section broke the 403 handler in registerNamespace, which directed users to it by name. That runtime guidance now links to the published guide, and the remaining "write-only app" phrasing is replaced with "Read and write" to match the permission level the UI shows. Sample-specific content is unchanged: Smee setup, credentials, running the server, expected terminal output, the helper function inventory, and webhook troubleshooting. Prerequisites was also left in place; it shares a heading with the guide but covers local tooling rather than the people and roles involved. Verified all 16 internal anchors resolve, the table of contents matches the headings, and every docs.github.com anchor referenced is live. Each endpoint to anchor pairing was checked against the x-github-internal path and http-method in the operation definitions. Lint and all 21 tests pass. 324 to 265 lines. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 97372c67-02e2-4b8b-a713-1d9e9c42f6ca
darthwillis
force-pushed
the
readme-dedupe-live-docs
branch
from
September 30, 2026 17:15
1536cf3 to
503f186
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Summary
The Integrating custom properties with an external system guide is now live. It covers what external custom properties are, display names and namespacing, the permission model, and installation behavior — and it links to this repository as the example implementation.
That establishes the division this PR applies: the docs own the concepts and setup, this README owns configuring and running the server.
What changed
Five areas restated GitHub behavior that the published docs now own. The concern isn't length, it's that each was an independent statement of platform behavior that can drift as the feature changes.
intro:frontmatter, the other itsexternal-properties-introreusable, down to the same examples (ownership, service tier, compliance status).DISPLAY_NAMEThat last one is the clearest example of the risk: the REST reference gained an authoritative statement of those rules the same day, so the README was a second, independently-maintained copy.
API Reference table
The table previously listed all six endpoints with links to their REST reference pages — the same six endpoints, with the same links, that the guide already lists under Create the automation.
Rather than delete it, the table now pairs each endpoint with the helper function in
example-server/app.jsthat calls it, and the endpoint path itself carries the reference link:POST /orgs/{org}/properties/installationsregisterNamespaceGET /orgs/{org}/properties/installationsgetRegisteredInstallationsGET /orgs/{org}/properties/installations/schemareadOrgSchemaPATCH /orgs/{org}/properties/installations/valueswriteExternalCustomPropertiesPATCH /orgs/{org}/properties/installations/values/{property_name}updateExternalCustomPropertyValuesDELETE /orgs/{org}/properties/installations/values/{property_name}deleteExternalCustomPropertyValuesThis keeps the reference one click away while making the column that remains something only this repository can provide. It also makes the README's existing claim that "each endpoint maps to a helper function" navigable rather than asserted.
324 → 265 lines.
What deliberately did not change
All sample-specific content is untouched: Smee proxy setup, credential and
.envconfiguration,npm installand the two-terminal run, expected terminal output, the helper function inventory, and webhook troubleshooting.Prerequisites was also left alone. It shares a heading with the guide's Prerequisites, but the content doesn't overlap — the guide describes the people and roles involved, while this describes local tooling (Node 24, an organization, a webhook proxy).
Verification
docs.github.comanchors referenced were confirmed present on the live pagesx-github-internal.pathandhttp-methodin the operation definitions, not matched by path alone — two rows share a path and differ only by method (PATCHvsDELETEon…/values/{property_name})app.js, and all six endpoint strings confirmed to be requested therenpm run lintclean, 21/21 tests passOne anchor broke during editing and was caught by the anchor check: Step 2 referenced the removed
#write-only-apps-org-admin-controlled-namespacingsubsection. It now points at the guide instead.