Connect GitHub

Connecting happens in two steps, and they are separate on purpose. First you give the workspace access to some repositories; then you pair one of them with a project.

Step 1 — install the app for the workspace

In workspace Settings → Repositories, start the GitHub App installation. GitHub asks which repositories the app may see: all of them, or a list you pick. Whatever you choose becomes the workspace’s pool — the set of repositories any project here can be paired with.

You can change that selection later on GitHub, and Meldoc notices: a repository you remove leaves the pool, and one you add appears in it.

The app needs Checks: read and write and the Pull request event if you want the Pre-Merge Check. An installation created before that permission existed has to accept it again — until it does, checks are refused and the run says so.

Step 2 — pair a repository with a project

Open the project, go to its Repositories panel, and look at the two tabs:

• Available lists what is in the pool and not yet connected here.
• Subscribed lists what this project is paired with.

Connect one from Available and the pairing exists. Meldoc syncs the repository’s default branch — it resolves which branch that is on every run, so renaming master to main does not quietly break anything.

Which files are documents, and where they live in the repository, comes from meldoc.config.yml in the repository — the same file the CLI reads. See Configuration.

Keep in mind: One repository can serve several projects. Each pairing is independent: its own runs, its own conflicts, its own pre-merge check.

Who did what

Everything the sync writes is attributed to the repository rather than to whoever pressed a button, so a document’s history reads as “the repository” and stays honest about where the text came from.

What’s next?

How a Sync Runs — What happens once the pairing exists.

Configuration — The meldoc.config.yml the sync reads.