GitHub Setup

Veckl uses GitHub in two different ways:

• A GitHub App reads and writes test case files in the configured repository.
• A GitHub OAuth App signs users in through the browser.

You can use GitHub.com or GitHub Enterprise Server.

Create the Test Case Repository

Create or choose the repository that will store Veckl data. It can be empty; Veckl can initialize the required files during first run.

The GitHub App installation must have access to this repository.

Create a GitHub App

Create a GitHub App for repository access.

Recommended repository permissions:

• Contents: read and write.
• Metadata: read.

After creating the app:

1. Record the App ID.
2. Generate and download a private key.
3. Install the app on the test case repository.
4. Record the installation ID.

Set these values in .env:

GITHUB_APP_ID=<your-github-app-id>
GITHUB_APP_INSTALLATION_ID=<your-installation-id>
GITHUB_APP_PRIVATE_KEY_PATH=/app/key.pem
GITHUB_OWNER=<your-org-or-username>
GITHUB_REPO=<your-repo-name>
GITHUB_BRANCH=main

For local development, either place the private key where GITHUB_APP_PRIVATE_KEY_PATH points or update the path to match your local file location.

Create an OAuth App

Create a GitHub OAuth App for sign-in.

For local development, use this callback URL:

http://localhost:3000/auth/github/callback

For a production deployment, use the public application origin:

https://<your-veckl-host>/auth/github/callback

Set the OAuth values in .env:

GITHUB_OAUTH_CLIENT_ID=<your-oauth-client-id>
GITHUB_OAUTH_CLIENT_SECRET=<your-oauth-client-secret>

Caution

The OAuth callback URL must match exactly. If it points at localhost:8080 while you use the frontend at localhost:3000, sign-in will redirect to the wrong place.

GitHub Enterprise Server

For GHES, set the API base URL:

GITHUB_API_BASE_URL=https://<ghes-host>/api/v3

If your GHES instance uses a private certificate authority, provide a CA bundle and set:

GITHUB_CA_BUNDLE_PATH=/app/ca-bundle.crt

Verify Access

Run:

./scripts/verify-env.sh .env
make dev

Then open http://localhost:3000 and sign in with GitHub. If the repository is reachable, the top bar shows the configured owner, repository, and branch.