GitHub project tracking for small teams

Overview

Standup status drifts from merged code. For code-backed work, Ravel can keep the plan honest as PRs merge, so progress follows what shipped, not what someone clicked.

You connect a repository once (repo name on the task, webhook in GitHub). After that, merges feed the map. The steps below cover setup first, then what happens when events are flowing.

Step 1: Confirm detail with your GitHub repo

After you review the draft plan, teams, tasks, and blockers, you land on the confirm detail view. This is where you bind GitHub by setting the repo full name on the task 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, and Ravel will email you the branch name, webhook URL, and secret for that repo.

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 includes the webhook URL and secret. Add both to the GitHub repo you confirmed.

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 and add the webhook. Once GitHub sends a successful ping, Ravel can track push activity for the 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