GitHub

Sync your vly project to a GitHub repository. Commit, branch, open PRs, run Actions — all from inside vly.

The GitHub integration mirrors your vly project to a GitHub repository. Every revision becomes a commit. Branches sync. Pull requests open from vly. GitHub Actions trigger on changes.

This is the bridge for teams that want vly’s velocity and their existing Git workflow.

What it does

Commit on every revision

Each prompt-completed revision in vly becomes a commit on the repo with a meaningful message.

Branch parity

Branches in vly map 1:1 to branches in GitHub. Create one in either place; it appears in the other.

Open PRs from vly

Click “Open PR” in the vly UI; the request appears in GitHub for review.

GitHub Actions still run

Your existing CI / lint / test workflows run on every push.

Setup

1. Connect your GitHub account

   1. In vly, Settings → Integrations → GitHub.
   2. Click Connect to GitHub.
   3. Authorize the vly GitHub App for the org / personal account that will own the repo.
2. Pick a repository

   Two options:

   Create a new repo

   vly creates a fresh repo (private by default), seeds it with the current state of the project, and starts syncing.

   Connect to an existing empty repo

   Useful if you want to set permissions or branch protection in advance. The repo must be empty — vly won’t overwrite existing files.

3. Choose the sync direction

   • vly → GitHub (default): vly is the source of truth. Direct pushes to GitHub are honored but vly may overwrite.
   • Bidirectional: hand-edits to the GitHub repo flow back into vly. Recommended for teams with existing Git workflows.

Code patterns vly generates

For features that interact with GitHub (issue tracking, CI status, deploy triggers), vly uses the Octokit library inside Convex actions.

Reading repo data

convex/github.ts

import { action } from "./_generated/server";
import { v } from "convex/values";
import { Octokit } from "@octokit/rest";

export const listIssues = action({
  args: { owner: v.string(), repo: v.string() },
  handler: async (_ctx, { owner, repo }) => {
    const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
    const { data } = await octokit.issues.listForRepo({ owner, repo, state: "open" });
    return data.map((i) => ({
      number: i.number,
      title:  i.title,
      url:    i.html_url,
      author: i.user?.login,
    }));
  },
});

Creating an issue

convex/github.ts

export const createIssue = action({
  args: {
    owner: v.string(),
    repo:  v.string(),
    title: v.string(),
    body:  v.string(),
  },
  handler: async (_ctx, args) => {
    const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
    const { data } = await octokit.issues.create(args);
    return { number: data.number, url: data.html_url };
  },
});

Webhook: react to push events

When you want vly to react when something happens in the repo (e.g., a PR is merged):

convex/http.ts

import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import crypto from "crypto";

const http = httpRouter();

http.route({
  path: "/api/github-webhook",
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    const sig    = req.headers.get("x-hub-signature-256");
    const event  = req.headers.get("x-github-event");
    const body   = await req.text();

    // Verify signature
    const expected = "sha256=" + crypto
      .createHmac("sha256", process.env.GITHUB_WEBHOOK_SECRET!)
      .update(body)
      .digest("hex");
    if (sig !== expected) return new Response("Bad sig", { status: 400 });

    const payload = JSON.parse(body);

    if (event === "pull_request" && payload.action === "closed" && payload.pull_request.merged) {
      // PR was merged — do something
      await ctx.runMutation(api.notifications.notify, {
        message: `PR #${payload.number} merged`,
      });
    }

    return new Response(null, { status: 200 });
  }),
});

export default http;

Configure the webhook URL (https://your-app.vly.app/api/github-webhook) in your repo’s Settings → Webhooks in GitHub.

Configuration

GITHUB_TOKEN · string · required

GitHub personal access token (PAT) or fine-grained token. Required for API calls. The vly app token works for repo-scoped operations.

GITHUB_WEBHOOK_SECRET · string

Webhook signing secret. Required only if you’ve registered webhooks against the repo. Set in repo Settings → Webhooks.

Common workflows

Run lint / tests on every PR

Add a .github/workflows/ci.yml to the repo (vly will commit it). GitHub Actions takes over from there. The vly editor can also surface action statuses inline.

Deploy to a third-party host

Add a workflow that triggers on push to main and deploys to Vercel, Netlify, or your own host. vly’s managed deployment continues to work in parallel.

Branch protection

Set GitHub branch protection on main requiring PR review. vly respects the protection — it won’t push directly to a protected branch; it’ll auto-open a PR instead.

Release tagging

On a successful production deploy, vly can create a Git tag matching the deploy version (v2026.04.18).

Co-editing with Cursor / VS Code

Clone the repo locally, edit in your favorite editor, push. Bidirectional sync brings the edits back to vly. Useful for deep refactors that benefit from a desktop editor.

Permissions and security

vly’s GitHub App requests the following permissions:

Permission	Why
Contents (read/write)	Sync code
Issues (read/write)	Create / read issues
Pull requests (read/write)	Open / manage PRs
Metadata (read)	Required for all GitHub Apps
Webhooks (write)	Auto-register webhooks for events vly needs to react to

You can revoke the integration at any time from GitHub → Settings → Applications → vly. Doing so disables sync immediately and the existing repo stays as-is.

Troubleshooting

Sync paused with 'permission denied'

The GitHub App’s access was revoked or the repo’s owner removed the app. Reconnect from vly’s integrations dashboard.

Hand-edits to GitHub not appearing in vly

Sync direction is set to vly → GitHub (one-way). Switch to Bidirectional in integration settings.

Conflicts during bidirectional sync

When the same file is edited in both vly and GitHub between sync events, vly opens a conflict-resolution UI. You pick the winning side per file.

GitHub Actions failing on vly-generated code

Usually a prettier / eslint style mismatch. Add a vly custom instruction describing your style rules; vly will match them.

Related

GitLab

Same model, different host.

Vercel

Deploy from your repo to Vercel in addition to vly’s managed hosting.

Branching in vly

How vly branches map to GitHub branches.