Sync your help articles with GitHub

Connect a repository under Settings → GitHub repositories. HelpWell then syncs the markdown files in its docs folder into your knowledge base each time you push to the tracked branch.

A product is one help center built from one or more repositories. You can connect an app, its API and its agent to the same product.

#Connect a repository

1. #Open the GitHub settings

   Go to Settings → GitHub repositories.

2. #Choose how to connect

   Select Connect GitHub. You can pick several repositories at once from a searchable checklist, with a Select all option.

   If your HelpWell server has a GitHub App, choose Install the GitHub app and pick the repositories. HelpWell binds the installation to your product only after GitHub confirms that you can see it.

   If the app is already installed, choose Connect an existing installation.

   If your server has no GitHub App, or you prefer a token, open Use an access token instead. This connects one repository at a time. Create a fine-grained token for that repository with Contents, Pull requests and Webhooks set to read and write.

3. #Set the branch and docs folder

   Each repository has a branch and a docs folder. HelpWell syncs only files under the docs folder.

4. #Set the three switches

   See the table below.

With a token, HelpWell stores it encrypted. It also creates the webhook itself, for push and release events, with its own secret. You do not add a webhook by hand.

#The three switches

If you ask a repository to sync a docs folder it does not have, HelpWell connects it for its code instead.

#Where articles appear

The first docs repository keeps its collections at the top level. Every other repository gets a folder in the knowledge base. By default the folder is the repository name, and its collections are prefixed with it.

For example, docs/guides/start.md in acme/api becomes api-guides/start.md. Paths and collections from different repositories never collide.

HelpWell skips a file in two cases:

• Another repository already has a file at that path.
• Another article already uses that article address.

Skipped files are listed in that sync.

#What happens when you push

1. HelpWell verifies the push (X-Hub-Signature-256) and queues that repository's sync.
2. It compares the branch with what HelpWell holds and fetches only the changed files under the docs folder.
3. It removes that repository's files that are gone. It never removes another repository's files.
4. It re-indexes the product once, after syncing every queued repository.

#Edit in HelpWell and send changes back

Edits made in HelpWell wait for a pull request to the repository they belong to. Select Open a pull request on that repository. A push never overwrites an edit that is still waiting.

A new article goes to the repository whose folder it is in. Otherwise it goes to the repository chosen under New articles.

#Check status

Each repository shows its status, last sync, edits waiting, last pull request and its own recent syncs.

Deleting a product also removes its GitHub webhook.