Keep GitHub documentation in sync with code
Keeping code and Markdown in the same repository does not ensure they agree. This guide follows a changed configuration default into a documentation correction, delivered through a GitHub pull request.
The example: code changes, but the configuration guide does not
This is an illustrative example, not a customer result. A landed code change raises the default request timeout from 30 to 60 seconds. The existing docs/configuration.md file still describes a 30-second default.
Before: “Requests time out after 30 seconds by default.”
Proposed correction: “Requests time out after 60 seconds by default.”
The code change supplies the evidence; the Markdown file is the document to maintain. Amendary proposes an edit to the stale passage and can deliver that edit as a docs pull request for your team to inspect and merge.
1. Set up a GitHub docs destination
Connect the repository using Getting started. A workspace owner then opens Pages → Add destination → GitHub, selects that repo, and chooses A folder in the repo. For this example, use docs and leave the branch blank to use the default branch.
Keep Open a pull request instead of committing directly enabled. The GitHub App needs write access for this destination. Connecting a source repo alone does not enable documentation writes.
2. Watch the existing Markdown page
Browse the GitHub destination on Pages and watch docs/configuration.md. Choose the Engineering docs audience and Docs & guides shape. A GitHub page maps to the repository it lives in; this example maintains code and documentation in the same repo.
Engineering documentation follows commits on the default branch, regardless of the repo’s customer-facing release trigger. Checks run daily, so an open product pull request is not itself a maintenance check. See Pages & mapping for the audience and trigger rules.
3. Review the correction in Amendary
Use review mode for this walkthrough. After the code change lands and is checked, inspect any proposed correction in the Queue. Confirm the source changes the default timeout, rather than setting a one-off timeout in a test or example. Compare the proposed sentence with the surrounding Markdown before applying it.
A check can find no supported mismatch and produce no correction. Amendary maintains the pages you watch; this does not guarantee every documentation problem will be detected. See Queue & reviews for applying or dismissing suggestions.
4. Inspect and merge the docs pull request
With the pull-request destination enabled, applying the correction writes the documentation edit to amendary/docs and opens or updates the docs pull request. Several documentation changes can collect in the same open PR.
Review its diff in GitHub, run your normal checks, and merge it when ready. Approval in Amendary and merging in GitHub are separate steps: the target branch still has the old text until you merge the PR. Afterward, open docs/configuration.md on that branch and verify the new default.
Other delivery options and boundaries
- A folder destination can commit directly if you turn off the PR option. Choose the delivery mode deliberately before applying corrections.
- A wiki destination writes to the repo wiki directly; the folder’s pull-request option does not apply to wiki edits.
- Each repo has one GitHub docs target: a folder or its wiki. Only workspace owners can enable or remove the destination.
- Amendary writes documentation, not application code. This workflow maintains existing Markdown; generating a new documentation set is a separate action.
- Automatic application on a paid plan still respects the destination’s delivery setting. It does not merge a docs PR for you.
If the update has not reached your docs
Check the watched page, source mapping, GitHub App write permission, and destination branch. Then check whether the correction is waiting in Amendary or its PR is still open in GitHub. For connection and check failures, see Troubleshooting. For documentation outside the repository, follow Update Notion documentation from GitHub changes.