Skip to content
Galley

Docs / Use

Connecting GitHub

Register a GitHub App or use a Personal Access Token, then connect repos to projects.

Galley needs three things from GitHub: ability to clone the repo, ability to receive PR webhooks, and ability to write status comments. There are two integration paths.

One install per org. Covers every repo in the org, including ones added later. Webhook deliveries are signed with a per-app secret.

Register the App

GitHub.com → Settings (org or personal) → Developer settings → GitHub Apps → New GitHub App. Use these values:

FieldValue
GitHub App nameGalley — yourco (must be globally unique)
Homepage URLhttps://galley.yourco.dev
Setup URLhttps://galley.yourco.dev/api/v1/git-connections/github/install/callback
Webhook URLhttps://galley.yourco.dev/api/v1/webhooks/github
Webhook secretGenerate a random string. Save it.
Where can this be installed?Any account

Permissions:

  • Repository → Contents — Read-only (clone)
  • Repository → Pull requests — Read & write (post comments)
  • Repository → Metadata — Read-only (auto)
  • Repository → Webhooks — Read & write (auto by App)

Subscribe to events:

  • Pull request
  • Push (optional — drives pull_request.synchronize reliably across edge cases)

After creating: generate a client secret and a private key (.pem). You’ll need both.

Wire it into Galley

In the dashboard: Admin → Instance → GitHub App and paste:

  • App ID (number from the App’s settings page)
  • Client ID + client secret
  • The .pem private key (paste the whole -----BEGIN ... END----- blob)
  • The webhook secret you generated

Galley encrypts the private key + secret under the master key. The page shows a green “configured” pill once the values round-trip a test.

Install on an org

Go to New project in the dashboard. The wizard takes you through the App’s install flow on GitHub: pick the org, pick repos (or “All repositories”), authorize. GitHub redirects back, the wizard auto-advances to the repo picker.

If you picked “All repositories”, new repos created later are visible to the App immediately. If you picked specific repos, you need to add new repos via GitHub → Settings → Applications → Your App → Configure.

Personal Access Token (PAT)

For solo accounts, internal-only setups, or repos you don’t have org-admin rights to install Apps on. Each PAT is one user’s identity, not an org-wide install.

  1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) (or fine-grained).
  2. Scopes: repo (or fine-grained: contents read, metadata read, pull requests write).
  3. Copy the token.
  4. In Galley New project wizard, pick Webhook + PAT and paste:
    • Username (your GitHub handle)
    • The token
    • A webhook secret (generate one yourself; you’ll add it on each repo)

Then on each repo: Settings → Webhooks → Add webhook:

  • Payload URL: https://galley.yourco.dev/api/v1/webhooks/github
  • Content type: application/json
  • Secret: same value you pasted into Galley
  • Events: pull request, push

PAT-driven projects only see repos the user owns or collaborates on. Adding a new repo means adding a new webhook by hand.

Webhook delivery and replay

Every delivery hits /api/v1/webhooks/github. The server:

  1. Verifies the HMAC signature against the connection’s webhook secret. Mismatch → 401, logged as rejected.
  2. Parses the event. Unsupported types are logged as ignored.
  3. Resolves the project from the repo’s external ID + connection.
  4. Creates / updates the PR record, queues a build.

The dashboard’s Admin → GitHub page shows the last 100 deliveries with their result. Each row has a Replay button — re-runs the original payload through the handler. Useful when a webhook missed (network blip on GitHub’s side) or when you’ve changed the project routing and want to retroactively pick up a missed PR.

Forks

By default, PRs from forks don’t trigger builds. Set Project settings → General → Build forked PRs if you want them to. The threat model is that fork PRs come from external contributors, so the build container would be running their code with your project’s secrets.

If you turn it on:

  • Don’t expose production secrets to forks. Use scoped or environment-specific values.
  • Pair with kind: api for backend services so screenshots don’t capture PII off the preview.
  • Consider IP allowlist on previews to limit who can hit the resulting URL.

Other providers

GitLab, Gitea, and Forgejo are on the roadmap. Today, GitHub is the only supported source.