GitHub sync isn't picking up my changes

Open Settings → GitHub repositories and look at the repository's row. If it says Needs attention, the error under it names the problem. If it says synced, the cause is usually the branch, the docs folder, a switch that is off, or a file that was skipped.

#1. Check the status and the error

Each row gives one line about the connection, for example Docs and releases · main · synced. Open Details on the row for more.

A repository in trouble shows Needs attention and the last error. For example: "GitHub could not find acme/acme-docs or its main branch." This means HelpWell can't see the repository or the branch you set. Check three things:

• The repository name is right.
• The branch exists.
• The token or GitHub app can still access the repository.

A failed sync also shows up in the bell menu.

#2. Check the switches

Each repository has three switches:

• Sync docs from this repo
• Use releases for changelog drafts
• Update articles from code changes

Articles only sync from a repository with Sync docs from this repo on. A repository used only for releases has nothing to sync, so it has no sync action on its row.

If you ask for a docs folder the repository doesn't have, HelpWell connects it for its code instead. Its articles then don't come from files.

#3. Check the branch and the docs folder

HelpWell syncs only the files under the repository's docs folder, on the branch you chose. Other files, such as README.md or code under src/, are not help content and are ignored.

A push to a tracked branch queues a sync. A push to any other branch doesn't. Each sync fetches only the files that changed, and it removes files from HelpWell that were removed from the repository. It never removes another repository's files.

#4. Look at Recent syncs and skipped files

Open Recent syncs on the row. Each sync lists how many files were fetched and removed, how many articles the repository has, and any skipped files with a reason.

A file is skipped when:

• Another repository already has a file at the same path.
• Another article already uses the same article address.
• Its slug can't be used (the reason shown is slug).

Rename the file or change its address, then push again.

#5. Look in the right place for the article

The first docs repository keeps its collections at the top level. Every other repository gets a folder in the knowledge base, by default named after the repository. Its collections are prefixed with that name. For example, docs/guides/start.md in acme/api becomes api-guides/start.md. If an article seems missing, look for the prefixed collection.

#6. Check the webhook

HelpWell adds the webhook to the repository itself, for push and release events, with its own secret. Open the repository's webhook settings on GitHub and check the webhook is still there. HelpWell verifies each push with X-Hub-Signature-256 before it queues a sync.

To pull changes without waiting for a push, use the sync action on the repository's row.

#7. Check the access

#Edits made in HelpWell

Edits you make in HelpWell don't go to the repository straight away. They wait until you choose Open a pull request on that repository. The row shows how many edits are waiting, for example Open a pull request (2 edits).