Connecting GitHub to Host

How Host gets access to your code, and — if you build for clients — how to connect a repository to a customer's organisation without handing them access to everything else you have.

The one thing to know first

GitHub allows only one installation of an app per GitHub account. A Waymaker organisation connects to an installation, not to a repository. So every repository that shares a GitHub account shares one installation, and any Waymaker organisation connected to it can reach all of them.

That constraint is GitHub's, not ours, and it produces a trap that is easy to walk into and awkward to walk back out of.

If you build for clients, read this before your first deploy

Say you keep your work in your personal GitHub account, and you have a Waymaker organisation per client. You are about to deploy you/acme-portal into Acme's organisation. Your installation already covers that repository, so connecting it takes one call and works immediately.

It also gives Acme's organisation deploy visibility of every other repository in your account — your other clients' code, and your own.

Nothing about the fast path looks wrong while you are doing it. Host now warns you and asks you to confirm before linking, and shows you exactly which repositories are in scope, but the warning is a guard rail, not the answer.

The answer: one GitHub account per client

Give each client their own GitHub account or organisation, owned by them where possible, and install the Waymaker app there with access limited to the repositories that client's apps need.

	Shared account	One account per client
Repos exposed to the client's org	all of them	only theirs
Client can take the code with them	no clean path	they already own it
Offboarding	untangle a shared installation	remove one installation
Your other clients if one org is compromised	reachable	untouched

The second column is also just better business. When the engagement ends, the client owns the account, the repository and the deployment history, and you remove one installation.

If the client has no GitHub presence and does not want one, keep the work in a dedicated account of yours — one per client, not a shared personal account — and transfer it later.

Connecting a repository

You do not need a browser, and the client does not need a Waymaker account.

1. Get an install link

waymaker host github install-url

Returns a link that is bound to your currently-selected organisation, single use, and valid for 30 minutes. The link is the whole credential — treat it like one, and fetch a fresh one per attempt rather than re-sending an old one.

Agents can call host_github_install_url for the same thing.

2. Send it to whoever administers the GitHub account

That is often you, not the customer — you are the one holding the repository. It is the customer only when the code is theirs.

When they approve on GitHub, the installation connects to the organisation the link was minted for. They do not need to be signed in to Waymaker, and they do not need an account at all.

3. Confirm

waymaker host github status

Shows the connected accounts and the repositories Host can see. If a repository you expected is missing, the app was probably installed with Selected repositories — add it on GitHub, then:

waymaker host github refresh-repos

Deploying a private repository without connecting GitHub at all

If you hold the code and just want it deployed, you can skip installation entirely by passing a personal access token at create time:

waymaker host apps create --name "Acme Portal" \
  --repo https://github.com/you/acme-portal \
  --github-token ghp_xxx

The token is stored encrypted and used only to clone at build time. It is the most direct path for a one-off deploy, and it grants the client's organisation nothing beyond that repository — but it also means redeploys depend on a token you own, so it suits a handover less well than a proper installation in the client's own account.

Telling Host how your app runs

Host works out whether your app is a static site or a server-rendered one by inspecting the repository. When you want to be certain rather than inferred — and you usually do for anything that queries a database on page load — declare it in the repository root:

// waymaker.config.ts
export default { type: "app", runtime: "server" } as const;

This is the strongest signal there is. It wins over automatic detection outright, it lives with the code, and it survives a rebuild, a re-import, or someone recreating the app.

Leave output_dir unset for a server-rendered app. Host builds and deploys the server for you. Setting it makes Host publish a folder of files instead, which for a server app means the pages load but nothing renders and no server code runs.

Never set output_dir to .next. It is Next.js's internal build folder, not a website — the deploy succeeds and every page 404s. Host now rejects it, but the reasoning is worth knowing: output_dir means "publish this folder as-is", and .next is scaffolding, not a site. Use out only if your next.config sets output: "export".

If a deploy says it cannot reach your repository

Host checks whether it can read the repository before it starts the first build, so an app whose source is not reachable is created in Needs repo access rather than failing a build. Nothing is broken and there is nothing to clean up — grant access and deploy.

Common causes, in order of likelihood:

1. The app is installed, but not on this repository. Selected-repositories scope. Add it on GitHub, then waymaker host github refresh-repos.
2. The repository is private and this organisation has no connection. Use the install link above, or pass --github-token.
3. The URL carries a suffix. https://github.com/you/repo.git and https://github.com/you/repo are both accepted, but a URL with extra path segments is not a repository URL.

Disconnecting

waymaker host github disconnect <installation-id>

Apps connected to that installation stay online at their current version; they stop rebuilding when you push. Reconnect at any time with a fresh install link.

An installation connected to one Waymaker organisation cannot be moved to another by connecting it again — whoever holds it has to disconnect first. That is deliberate: it means nobody can quietly re-point your source connection.