Overview
This document describes how code changes are reviewed, approved, and merged into the production branch (main) of our source repositories. The process applies to all repositories whose artifacts run in production and to all engineers and automated systems with write access.
Branching Model
We use a trunk-based model with short-lived feature branches:
- main — the protected production branch. Always deployable. Direct pushes are disabled.
- feature/* — short-lived branches created from main for new work.
- hotfix/* — branches for expedited production fixes.
Branch Protection
The main branch enforces the following rules in the source control platform:
- Direct pushes disabled (including for administrators).
- Force-push and branch deletion disabled.
- At least one approving review required from someone other than the author.
- Code Owner approval required for protected paths (CODEOWNERS).
- All required status checks must pass before merge.
- Branch must be up to date with main before merge.
- Signed commits required.
- Linear history required (squash or rebase merges only).
Merge Process
Every change to the production branch follows these steps:
1. Create a feature branch
The engineer creates a feature branch from the latest main and links the work to a ticket in our issue tracker. The ticket captures the change description and any rollback considerations.
2. Open a pull request
When the change is ready, the engineer opens a pull request using our standard template. The PR includes a summary, the linked ticket, test evidence, and any deployment notes.
3. Automated checks run
The CI pipeline runs automatically on every push. The following checks must all pass before merge is allowed:
- Unit and integration tests
- Static Application Security Testing (SAST)
- Software Composition Analysis (dependency vulnerability scan)
- Secrets scanner
- Linter and code style checks
- Build and artifact creation
4. Peer code review
At least one engineer who is not the author reviews the change. Reviewers verify functional correctness, security, error handling, and adequate test coverage. Any feedback is resolved in the PR. New commits dismiss prior approvals, which must be re-issued.
5. Merge
Once all required checks are green and the required approval is in place, the PR is squash-merged into main. The merge commit references the ticket ID. Self-merging without independent approval is technically prevented by branch protection.
6. Deploy
Deployment to production is executed automatically by the CI/CD pipeline from the merge commit on main. Engineers do not deploy manually. The pipeline runs post-deploy health checks; failure triggers an automated rollback.
Required Status Checks
The following checks are configured as required in the SCM platform and block merge if they fail:
| Check | Purpose |
|---|---|
| Unit + integration tests | Verify functional correctness and prevent regressions. |
| SAST | Detect source-level security vulnerabilities. |
| Dependency scan | Detect known CVEs in third-party libraries. |
| Secrets scanner | Prevent credentials from being committed to the repository. |
| Build | Confirm the change produces a deployable artifact. |
Hotfix Process
Emergency changes addressing active incidents or security issues follow the same process with the following adjustments:
- An incident ticket is opened and a hotfix branch is created from main.
- All required automated checks still apply and are not bypassed.
- A second engineer provides synchronous review and approval. Self-approval remains prohibited.
- Engineering leadership is notified before merge.
Audit Trail
The following are retained automatically for every change:
- Pull request history (author, reviewers, approvers, comments, timestamps).
- CI status check results, including all security scan outputs.
- Build and deployment logs.
- Branch protection configuration.