GitHub Integration

Waymaker Host uses a GitHub App to access your repositories for building and deploying apps and ambassadors.

How It Works

1. You install the Waymaker GitHub App on your GitHub account or organization
2. The installation is linked to your Waymaker organization
3. When you create an app or ambassador with a repository URL, Waymaker uses this installation to access the code
4. Push events trigger automatic deployments

Installing the GitHub App

From the Host UI

1. Navigate to Host in Commander
2. Click Connect GitHub
3. You'll be redirected to GitHub to authorize the Waymaker App
4. Choose which repositories to grant access to
5. Confirm the installation

Checking Installation Status

waymaker host github status

This lists all GitHub App installations linked to your organization, including:

• GitHub account login
• Account type (user or organization)
• Accessible repositories
• Installation date

Linking an Installation

If you've already installed the GitHub App and need to link it to your Waymaker organization:

waymaker host github connect --installation-id 12345678

The installation ID comes from GitHub's installation callback URL.

Disconnecting

Remove a GitHub installation link:

waymaker host github disconnect --installation-id 12345678

This only removes the link in Waymaker — the GitHub App remains installed. Apps using this installation will lose auto-deploy capabilities.

Repository Access

The Waymaker GitHub App requests these permissions:

Permission	Scope	Purpose
Contents	Read	Access code for builds
Metadata	Read	List repos and branches
Actions	Write	Trigger build workflows

Auto-Detection

When you create an app, Waymaker automatically:

1. Looks up your organization's GitHub installation
2. Uses it to detect the framework from your repo
3. Suggests build command and output directory
4. Links the installation for future deployments

You don't need to specify a github_installation_id when creating apps — it's looked up automatically.

Multiple GitHub Accounts

An organization can have multiple GitHub installations. This is useful if your code is spread across:

• A personal GitHub account
• A GitHub organization
• Multiple GitHub organizations

Each installation grants access to different repositories. When creating an app, Waymaker uses the most recent installation by default.

Troubleshooting

"No GitHub installation found"

• Verify the GitHub App is installed: check GitHub Settings > Applications
• Run waymaker host github status to see linked installations
• If recently installed, try waymaker host github connect with the installation ID

"Repository not accessible"

• The GitHub App may not have access to that specific repository
• Go to GitHub Settings > Applications > Waymaker > Configure
• Add the repository to the allowed list

Builds fail with "clone failed"

• The repository URL must match exactly (including .git suffix if used)
• Verify the branch name exists in the repository
• Check that the GitHub App installation hasn't been suspended