GitHub Integration

Connect a GitHub repository to your Virke project for automatic deployments on push and preview deployments per pull request.

Quick Start

Link a repository

virke link owner/repo

This connects the repository and enables:

  • Auto-deploy on push to the tracked branch (default: main)
  • Preview deploy per PR with a unique URL posted as a PR comment

Track a specific branch

virke link owner/repo --branch production

Unlink

virke unlink

How It Works

GitHub push event
       ↓
Virke GitHub App webhook
       ↓
Virke API receives event
       ↓
Clone repo → detect framework → build → deploy
       ↓
Update deployment status on GitHub
  1. When you virke link, Virke installs a GitHub App on your repository
  2. On push to the tracked branch, GitHub sends a webhook to the Virke API
  3. The API clones your repo, runs the build, and deploys the output
  4. Deployment status is reported back to GitHub as a commit status check

Auto-Deploy on Push

Every push to the tracked branch triggers a production deployment. The build uses your virke.toml configuration — same build command, same output directory.

Commit status checks

Virke posts deployment status as GitHub commit status checks:

Status Meaning
pending Build started
success Deployed successfully
failure Build or deploy failed

The status check includes a link to the deployment URL.

Preview Deployments per PR

Every pull request automatically gets a preview deployment at a unique URL. The preview URL is posted as a PR comment.

Preview deployed: https://preview-abc123.my-app.virke.dev

Preview lifecycle

Event Action
PR opened Build and deploy preview
PR updated (new commits) Rebuild and update preview
PR merged or closed Preview is cleaned up

Preview deployments are isolated — they do not affect production traffic.

Configuration

virke.toml

[project]
name = "my-app"

[github]
repo = "owner/repo"
branch = "main"              # branch to auto-deploy (default: main)
preview = true               # enable preview deploys per PR (default: true)

Build environment

The GitHub build environment includes:

Variable Value
VIRKE_DEPLOY_SOURCE github
VIRKE_COMMIT_SHA Full commit SHA
VIRKE_BRANCH Branch name
VIRKE_PR_NUMBER PR number (preview deploys only)

Dashboard Setup

You can also connect a GitHub repository from the Dashboard:

  1. Go to Project Settings > GitHub
  2. Click Connect Repository
  3. Authorize the Virke GitHub App
  4. Select the repository and branch

Comparison with CI/CD

Feature GitHub Integration CI/CD (manual)
Setup virke link (one command) Write workflow YAML
Build runs on Virke infrastructure Your CI runner
Preview per PR Automatic Manual workflow setup
Build minutes Included in plan Your CI provider
Customization virke.toml Full control

Use GitHub Integration for the simplest setup. Use CI/CD when you need custom build steps, monorepo support, or want builds on your own infrastructure.

Troubleshooting

Deployments not triggering

  1. Verify the repository is linked: check Project Settings > GitHub in the Dashboard
  2. Verify you're pushing to the tracked branch
  3. Check that the Virke GitHub App is still installed on the repository

Build failures

Check the deployment log in the Dashboard under Deployments > [deployment] > Build Log. Common issues:

  • Missing build script in package.json
  • Missing dependencies (not in package.json)
  • Build command mismatch between local and virke.toml

Preview URL not posted on PR

Verify preview = true in virke.toml (it's the default). The Virke GitHub App needs write access to post PR comments.

Further Reading