GitHub project tracking & sync

Overview

GitHub sync connects a repository to your Ravel project through a webhook. Setup happens right after AI decomposition: you confirm the plan with a GitHub repo full name, receive webhook details by email, then paste them into GitHub. This page walks through that flow first, then explains what sync does once events are flowing.

Step 1 — Confirm detail with your GitHub repo

After Ravel decomposes your project into departments, tasks, and dependencies, you land on the confirm detail task view. This is where you bind GitHub by setting the repo full name on the task detail before the project is finalized.

1. Review the proposed graph, then open the confirm detail task view for the code-backed task you are finalizing.
2. Check task details: owner, owner email, completion type, dependencies, and due date.
3. In the Repo field, enter your GitHub repository full name (format: owner/repo, e.g. acme/web-app).
4. Confirm the plan. Ravel saves the project and sends you an email with the branch name, webhook Payload URL, and Secret for that repository.

Step 2 — Create the branch from the email

The confirmation email does not just include webhook details. It also gives you the branch name Ravel expects for this task. Create that branch before you start coding so GitHub activity maps cleanly back to the task.

1. Open the email from Ravel and copy the branch name for the task you just confirmed.
2. In your local repository, switch to the default branch and pull the latest changes.
3. Create a new branch with the exact name from the email, for example: git switch -c feat/login-ui-ravel.
4. Start work on that branch. Pushes from this branch are what Ravel uses to track progress for the connected task.

Step 3 — Add the webhook in GitHub

The same email also contains the Payload URL and Webhook secret for the repo you confirmed. Add them in GitHub — do not invent or reuse values from another project.

1. On GitHub, open the repository you entered (owner/repo) → Settings → Webhooks → Add webhook.
2. Paste the Payload URL from Ravel’s email into the Payload URL field. Set Content type to application/json.
3. Paste the Webhook secret from the email into the Secret field. Leave SSL verification enabled.
4. Under “Which events would you like to trigger this webhook?”, choose “Just the push event.”
5. Check Active, then click Add webhook. When GitHub delivers the ping successfully, Ravel can receive push activity for this project.

What GitHub sync does

Once the webhook is live, push activity on the connected repo feeds into task progress for code-backed work. Ravel evaluates activity against each task’s scope — not as a generic activity feed — and marks work complete when the code actually ships.

When a GitHub-backed task finishes, dependent tasks unlock on the graph and owners are notified by email. Status reflects merged reality, not manual status clicks.

Tasks that do not ship as code are unchanged: they can complete via upload, external link, or manual confirmation. GitHub tracking applies to tasks configured for PR or commit-based completion on this repo.

GitHub events Ravel uses