GitHub Integration

Connect your GitHub repositories to Telbase for automatic deploys on every push. Link a repo, choose a branch, and every commit triggers a deploy with status checks reported back to GitHub.

Connecting GitHub

Install the Telbase GitHub App

Run the connect command or go to Settings → GitHub in the dashboard. This opens GitHub to install the Telbase app on your account or organization.

bash

telbase github connect

Authorize access

Grant the Telbase app access to the repositories you want to deploy. You can choose specific repos or grant access to all repos in an organization.

Confirm the connection

Once authorized, the CLI confirms the connection. You can now link repositories to your Telbase projects.

bash

telbase github status

Linking a Repository

Link a GitHub repository to an existing Telbase project. You must deploy at least once (or run telbase init) before linking.

bash

# Link a repo to the current project
telbase github link owner/repo

# Verify the link
telbase github status

Each project can be linked to one repository. Linking a different repo replaces the previous link. For monorepos, set a root directory to deploy from a subdirectory.

You can also link a repo from the dashboard. Open your project, go to Settings → GitHub, select a repository, and choose a deploy branch.

Auto-link from deploy

When you deploy with telbase deploy --repo URL, Telbase automatically links the repo for push-to-deploy after a successful deploy. Use --no-link to skip auto-linking.

Auto-Deploy on Push

Once linked, pushes to the configured branch automatically trigger a deploy. The GitHub webhook fires on every push, and Telbase starts a deploy using the latest commit.

Branch filtering

Only pushes to the configured deploy branch trigger a deploy. Pushes to other branches are ignored. This means you can safely push to feature branches without triggering production deploys.

For multi-service projects, Telbase maps changed files to services and only redeploys services affected by the push. Unchanged services are skipped automatically.

Deploy Branch

By default, Telbase deploys from the main branch. Change the deploy branch if your project uses a different branch for production:

bash

# Change deploy branch to develop
telbase github branch develop

# Check current branch configuration
telbase github status

You can also change the deploy branch from the dashboard in Settings → GitHub.

Root Directory

For monorepo projects where your app lives in a subdirectory, set the root directory so Telbase knows where to find the source code. Only files within this directory are used for framework detection and deployment.

bash

# Set root directory when linking
telbase github link owner/repo --root-dir apps/web

In the dashboard, enter the root directory path when linking a repo, or update it later in Settings → GitHub.

Commit Status

Telbase reports deploy status back to GitHub as commit status checks. This gives you deploy feedback directly on commits and pull requests:

Pending — deploy started, build in progress
Success — deploy completed, includes a link to the live URL
Failure — deploy failed, includes a link to build logs

Preview environments

Want a unique preview URL for each pull request? Enable preview environments to deploy a live preview for every PR. See Preview Environments below.

Preview Environments

Preview environments deploy a live preview of every pull request, giving reviewers a unique URL to test changes before merging. Each preview is accessible at a URL like pr-42-my-app.telbase.ai.

Enabling previews

Preview environments are opt-in. Enable them from the dashboard in Settings → GitHub by toggling PR Preview Deploys.

Requirements

Preview environments are available for Vercel-hosted single-service projects that have at least one successful deploy. GCP-hosted and multi-service projects are not supported yet. Each preview counts against your monthly deploy quota.

How it works

PR opened or updated

When a pull request is opened, pushed to, or reopened against the deploy branch, Telbase automatically starts a preview deploy using the PR branch code.

Preview deployed

Once the build completes, Telbase posts a comment on the PR with a table showing status, branch, commit, and a live preview URL. A telbase/preview commit status check is also reported on the PR.

PR closed or merged

When the PR is closed or merged, the preview environment is automatically cleaned up and the preview URL stops working.

Preview URL format

Preview URLs follow the pattern pr-N-slug.telbase.ai, where N is the PR number and slug is your project slug. For example, PR #42 on a project called “my-app” would be accessible at pr-42-my-app.telbase.ai.

Limitations

Vercel single-service only — GCP-hosted and multi-service projects do not support preview environments yet.
No fork PRs — for security, pull requests from forks are skipped.
Quota applies — each preview deploy counts against your monthly deploy limit.
Deploy branch only — only PRs targeting the configured deploy branch trigger previews.

Managing Connections

bash

# View connection and link status
telbase github status

# Unlink the current project from its repo
telbase github unlink

# Disconnect GitHub entirely (removes all links)
telbase github disconnect

Unlinking a project stops auto-deploy for that project but keeps the GitHub connection active. Disconnecting removes the GitHub App installation and all repository links.

Next Steps

CLI Reference — full github command reference with all flags
Supported Frameworks — frameworks auto-detected on deploy
Full-Stack & Monorepos — multi-service projects and per-service deployment