01
Store repo_url
Set the repository URL in app config so the agent knows which app owns that repo.
GitHub and webhooks
GitHub integration is just app config plus a signed webhook.
Relay does not need a hosted Git provider abstraction. The agent stores the repo URL for an app, GitHub posts push events to the agent, and Relay decides which app/env/branch should deploy.
Webhook endpoint
POST http://<agent-host>:8080/api/webhooks/github
Content-Type: application/json
X-Hub-Signature-256: sha256=...Webhook flow
A push lands in GitHub, GitHub calls the agent, the agent matches app state.
The agent reads the repository URL and branch from the webhook payload, then checks app_state rows to find the app/env/branch that should deploy. If there is a per-app webhook secret, it is used first.
02
Add the webhook
Point GitHub at `/api/webhooks/github` on the Relay agent.
03
Verify the signature
Relay checks the per-app secret when present, otherwise the global fallback secret.
04
Start the deploy
A matching push triggers the same build and rollout path as a manual deploy.
Connecting a repo
The important piece is app configuration, not a separate GitHub app.
Relay stores repository metadata per app/env/branch. That lets the webhook handler know where a push should go and gives the dashboard enough information to display repository details.
repo_url
The Git remote used to match incoming webhooks.
branch
The branch this app slot should deploy from.
env
Usually preview or prod, but stored explicitly.
webhook_secret
Optional per-app secret used instead of the global fallback.
App config payload
{
"app": "demo",
"env": "preview",
"branch": "main",
"repo_url": "https://github.com/org/repo.git",
"webhook_secret": "super-secret"
}Secrets and safety
Prefer per-app webhook secrets over one global secret.
Per-app secrets make it easier to isolate repositories and rotate one integration at a time. The global RELAY_GITHUB_WEBHOOK_SECRET still works as a fallback, but it should not be your only control if multiple repos share the same agent.
Checklist
Expose the webhook endpoint only on the agent you intend GitHub to reach.
Set an explicit webhook secret in the project settings or app config.
Keep the general Relay API token separate from GitHub webhook auth.
Use HTTPS and a stable hostname if the agent is reachable from the public internet.
GitHub webhook settings
URL: http://<agent-host>:8080/api/webhooks/github
Content type: application/json
Secret: <per-app-secret>
Events: push