> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Commit on every revision" icon="git-commit">
    Each prompt-completed revision in vly becomes a commit on the repo with a meaningful message.
  </Card>

  <Card title="Branch parity" icon="git-branch">
    Branches in vly map 1:1 to branches in GitHub. Create one in either place; it appears in the other.
  </Card>

  <Card title="Open PRs from vly" icon="git-pull-request">
    Click "Open PR" in the vly UI; the request appears in GitHub for review.
  </Card>

  <Card title="GitHub Actions still run" icon="cog">
    Your existing CI / lint / test workflows run on every push.
  </Card>
</CardGroup>

## Setup

<Steps>
  <Step title="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.
  </Step>

  <Step title="Pick a repository">
    Two options:

    <Tabs>
      <Tab title="Create a new repo">
        vly creates a fresh repo (private by default), seeds it with the current state of the project, and starts syncing.
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Code patterns vly generates

For features that interact with GitHub (issue tracking, CI status, deploy triggers), vly uses the [Octokit](https://github.com/octokit) library inside Convex actions.

### Reading repo data

```typescript convex/github.ts theme={null}
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

```typescript convex/github.ts theme={null}
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):

```typescript convex/http.ts theme={null}
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

<ParamField path="GITHUB_TOKEN" type="string" required>
  GitHub personal access token (PAT) or fine-grained token. Required for API calls. The vly app token works for repo-scoped operations.
</ParamField>

<ParamField path="GITHUB_WEBHOOK_SECRET" type="string">
  Webhook signing secret. Required only if you've registered webhooks against the repo. Set in repo Settings → Webhooks.
</ParamField>

## Common workflows

<AccordionGroup>
  <Accordion title="Run lint / tests on every PR" icon="check-circle">
    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.
  </Accordion>

  <Accordion title="Deploy to a third-party host" icon="cloud-upload">
    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.
  </Accordion>

  <Accordion title="Branch protection" icon="lock">
    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.
  </Accordion>

  <Accordion title="Release tagging" icon="tag">
    On a successful production deploy, vly can create a Git tag matching the deploy version (`v2026.04.18`).
  </Accordion>

  <Accordion title="Co-editing with Cursor / VS Code" icon="code-2">
    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.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Sync paused with 'permission denied'" icon="alert-triangle">
    The GitHub App's access was revoked or the repo's owner removed the app. Reconnect from vly's integrations dashboard.
  </Accordion>

  <Accordion title="Hand-edits to GitHub not appearing in vly" icon="alert-triangle">
    Sync direction is set to **vly → GitHub** (one-way). Switch to **Bidirectional** in integration settings.
  </Accordion>

  <Accordion title="Conflicts during bidirectional sync" icon="alert-triangle">
    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.
  </Accordion>

  <Accordion title="GitHub Actions failing on vly-generated code" icon="alert-triangle">
    Usually a `prettier` / `eslint` style mismatch. Add a vly [custom instruction](/building/custom-instructions) describing your style rules; vly will match them.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={3}>
  <Card title="GitLab" icon="gitlab" href="/integrations/gitlab">
    Same model, different host.
  </Card>

  <Card title="Vercel" icon="triangle" href="/integrations/vercel">
    Deploy from your repo to Vercel in addition to vly's managed hosting.
  </Card>

  <Card title="Branching in vly" icon="git-branch" href="/building/branching">
    How vly branches map to GitHub branches.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.