GitHub

Connect GitHub when your TeaHouse needs repository-aware team workflows.

The GitHub integration is separate from your local Git setup. Your terminal still uses the Git remote, SSH keys, credential helper, and gh or Git commands already configured on your machine.

What GitHub connects

Once GitHub is connected, Coldtea can:

• Confirm repository access for team and cloud-agent flows.
• Tie a repository identity to a Coldtea project.
• Receive pull request and deployment webhooks, which trigger QA runs on the right commit.
• Resolve Mobile CI artifacts from GitHub Actions for PR-triggered Android or iOS QA.
• Post PR reports back to the pull request.

GitHub App and personal token

Coldtea reaches a repository two ways:

• A GitHub App installation on the organization or account, with access granted to specific repositories. This is the usual path for team and cloud-agent flows.
• The owner's personal GitHub token, used when no App installation covers the repository. This lets Coldtea read a repository the App has not been installed for.

For repository-scoped features, installing the App is not enough on its own. The App also needs access to the specific repository.

Before you connect

Check three things:

• You are signed in to the right Coldtea TeaHouse.
• You are signed in to the right GitHub account in the browser.
• That GitHub account can install or manage access for the target repository.

If you cannot grant repository access in GitHub, Coldtea cannot work around that from the desktop app.

Connect GitHub

The usual flow is:

1. Open the GitHub integration in Coldtea settings.
2. Start the connection or App installation flow.
3. Complete the GitHub browser handoff.
4. Grant access to the repositories your team wants Coldtea to use.
5. Return to Coldtea and wait for the status to show connected.

Pull request and deployment webhooks

Once the App has access to a repository, GitHub sends Coldtea webhooks for pull requests, pushes, and deployment status. Coldtea uses them to start QA runs against the right commit: a web run waits for a preview deployment to report ready, while a mobile run keys off the pull request itself. This is what drives PR-triggered QA and the report that lands back on the pull request.

If access looks wrong

Check in this order:

• The active TeaHouse is the one where GitHub was connected.
• The browser completed the connection successfully.
• The GitHub App is installed for the organization or account you expected.
• The target repository is included in the installation's repository access.
• Your GitHub account has permission to manage that installation.

If the local terminal cannot push or fetch, debug local Git credentials instead. GitHub integration status does not replace your normal Git remote setup.

Security note

Grant the smallest repository access that supports the workflow. Team integrations may sync selected repository, task, PR, deployment, or QA metadata depending on the feature used.

Next: Linear or teams and security.