Git workflow for HASH including branch naming, PR creation, and PR reviews. Use when creating branches, making commits, opening pull requests, or reviewing PRs.
Git workflow for HASH including branch naming, PR creation, and PR reviews. Use when creating branches, making commits, opening pull requests, or reviewing PRs.
Use uppercase 'H' in PR titles (unlike branch names)
Keep description clear and concise
Examples:
H-4922: Add branch naming instructions
H-1234: Implement user authentication system
H-5678: Fix database connection timeout
PR Template
Use the template at .github/pull_request_template.md. Key sections:
Purpose - High-level explanation of what and why
Related links - Linear issues, discussions, context
What does this change? - Specific implementation details
Pre-merge checklist:
Publishable library changes (npm/Cargo)
Documentation requirements
Turbo Graph impact
Known issues - Intentional omissions or limitations
Next steps - Planned follow-ups
Tests - Automated test coverage
How to test - Manual testing instructions
Demo - Screenshots or videos
Merge Queue
hashintel/hash merges through a GitHub merge queue. This changes both how a PR is enqueued and how that can be verified.
auto_merge is not evidence
Enqueuing a PR ("Merge when ready") does not populate the PR's auto_merge field — it stays null even on a completely successful enqueue. Never verify an enqueue by reading auto_merge: it reads null in the success case and the failure case alike, so it carries no information.
Verified 2026-07-31 on PR #9127: a human's successful enqueue at 14:07:40Z produced no auto_merge_enabled event and no auto_merge value — indistinguishable from a "failed" one.
Verifying an enqueue
Use either:
a recent added_to_merge_queue event in GET /repos/hashintel/hash/issues/<NUMBER>/timeline
fresh merge_group workflow runs on a gh-readonly-queue/<base>/pr-<NUMBER>-<sha> ref
Re-queuing after an ejection
Re-queuing works from agent sessions via the GitHub MCP enable_pr_auto_merge tool. Its response is success-shaped with an empty method and enabled at — that empty shape is the expected signature of the repo routing to the queue instead of creating an autoMergeRequest, not a failure. (Verified on #9127: added_to_merge_queue by claude[bot] at 14:29:23Z, merge_group CI restarted 23s later, merged unattended at 14:48:59Z with merged_by: claude[bot], no human action.)
What does not work:
GraphQL enablePullRequestAutoMerge via curl — proxy-blocked in agent sessions ("only the pinned set of PR-review operations is served")
REST PUT /repos/hashintel/hash/pulls/<NUMBER>/merge — rejected for queue-protected branches, and it would bypass the queue rather than enter it
Diagnosing an ejection
An ejection can be another PR's fault, or nobody's:
The gh-readonly-queue/... ref names every PR in the batch. If only yours is named, it was not batched with another.
Before treating an ejection as a defect in your diff, compare the failing step against the same step on the identical head in the PR-level run. A step that took 17 seconds there and timed out in the queue is infrastructure, not code. Do not push a "fix" for a flake.
The queue lints differently from the PR
The PR runs cargo clippy --all-features; the merge queue runs cargo hack --optional-deps --feature-powerset clippy, dispatched on GITHUB_EVENT_NAME in the .justfile. turbo.json also puts GITHUB_EVENT_NAME in the lint:clippy task's env, so the queue cannot replay the PR's cache. The queue can therefore legitimately surface feature-conditional problems the PR lint never ran — including the package-level warning: unused dependency gate that lint.yml greps for and fails on.
Before reporting a failure
Do not tell a human you were unable to do something without verifying that claim first, and re-check current state before asking them to do something you already attempted.
PR Review Process
Step 1: Gather Information
Run these commands to get full context:
# View PR metadata, description, and comments
gh pr view <PR_NUMBER> --comments
# View ALL changes (do not truncate)
gh pr diff <PR_NUMBER>
# View inline diff comments
gh api \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
/repos/hashintel/hash/pulls/<PR_NUMBER>/comments
Important: Always view the FULL diff. Do not pipe into head or use --name-only.
Step 2: Check Linear Issues
Look for H-XXXX references in the PR title/description, then fetch the issue:
# If Linear MCP is configured:
mcp__linear__get_issue --issueId "H-XXXX"# Or use Linear web UI
Use the Linear issue requirements as baseline for the review.
Step 3: Provide Feedback
Be precise about issue locations (file:line)
Include suggestions for improvement
Reference relevant code standards
Distinguish blocking issues from suggestions
Quick Reference
Action
Format
Branch name
<shortname>/h-XXXX-description
PR title
H-XXXX: Description
View PR
gh pr view <NUMBER> --comments
View diff
gh pr diff <NUMBER>
View comments
gh api /repos/hashintel/hash/pulls/<NUMBER>/comments
