Version 1.0

Status Active

Owner Head of Engineering

Last Updated 2026-06-08

SOP: Git Flow and Branching

1. Purpose

The purpose of this SOP is to define a simple and consistent Git workflow for creating branches, opening Pull Requests, merging changes, and promoting code between environments.

This SOP exists to make code movement predictable, traceable, and safe.

The goal is to ensure that everyone understands:

which branches should be used,
where new work should start,
where Pull Requests should be opened,
how changes reach the development environment,
how changes are promoted to staging,
and how approved changes reach production.

2. Scope

This SOP applies to all repositories and engineering changes managed through GitHub.

It applies to:

Frontend frontend application code,
Backend backend application code,
DevOps infrastructure, CI/CD, deployment, and environment configuration,
QA test automation and QA tooling,
Engineering shared scripts, documentation, and repository configuration.

This SOP does not replace the Ticket Management SOP, Pull Request SOP, QA SOP, or Deployment SOP. It defines the branching and code promotion model that connects those processes.

3. Core Rule

Mandatory All engineering changes must be made through a working branch and merged through a Pull Request.

Direct commits to development or main are not allowed during normal work.

The default flow is:

working branch → Pull Request → development → staging → main → production

The development branch is the default integration branch. The main branch is the production branch.

4. Rule Strictness

Level	Meaning
Mandatory	Must be followed unless there is an approved and documented exception.
Default	Should normally be followed, but exceptions are allowed when justified.
Recommended	Encouraged, but not strictly required in every case.

5. Definitions

Term	Meaning
`main`	The production branch. Code in this branch represents code approved for production deployment.
`development`	The integration branch. Normal work is merged here first and automatically deployed to the development environment.
Working Branch	A short-lived branch created from `development` for a specific change.
Pull Request / PR	A GitHub request to merge changes from one branch into another branch.
Development Environment	The environment automatically updated after a PR is merged into `development`.
Staging Environment	The environment used for manual QA verification and release candidate testing.
Production Environment	The live environment used by real users.
Promotion	The process of moving approved code from one environment or branch toward the next stage.
Hotfix	An urgent fix for a critical production issue.

6. Roles and Responsibilities

Role	Responsibilities
Developer	Creates working branches from `development`, keeps branches focused, opens PRs, and follows the Pull Request SOP.
PR Author	Owns the working branch and PR until the PR is merged or closed.
Reviewer	Reviews PRs before merge according to the Pull Request SOP.
QA	Verifies changes in the appropriate environment before production promotion when QA verification is required.
DevOps	Supports branch protection, CI/CD, environment deployment, and deployment troubleshooting.
Responsible Individual / Team	Manually deploys approved versions to staging or production when authorized to do so.
Head of Engineering	Owns the Git flow process, approves exceptions, and resolves escalations.
Authorized Approver	A person with the appropriate repository or deployment role who may approve exceptional actions, such as direct commits, emergency merges, or rule bypasses, only when justified and documented.

7. Branches

7.1 Production branch: main

Mandatory The main branch is the production branch.

Code should reach main only after it has been reviewed, merged into development, deployed to staging when required, and approved for production.

Normal feature, fix, task, and refactor branches must not be merged directly into main.

Production deployment is performed manually from main by the responsible individual or team.

7.2 Integration branch: development

Mandatory The development branch is the default integration branch.

All normal work must be merged into development through a Pull Request.

After a PR is merged into development, the latest changes are automatically deployed to the development environment.

7.3 Working branches

Mandatory Working branches must be created from development.

A working branch should be short-lived and focused on one ticket or one logical unit of work.

Working branches should be deleted after their PR is merged unless there is a clear reason to keep them.

8. Branch Naming

Default Branch names should use a clear prefix that describes the purpose of the work.

Ticket IDs are recommended when useful, but they are not mandatory.

Branch names should be lowercase, descriptive, and use hyphens between words.

8.1 Recommended branch prefixes

Prefix	Use For	Example
`feature/`	New functionality or user-facing features	`feature/password-reset-flow`
`fix/`	Bug fixes or defect corrections	`fix/login-expired-session`
`chore/`	Maintenance work, dependency updates, small operational changes	`chore/update-dependencies`
`refactor/`	Code restructuring without intended behavior change	`refactor/auth-service-cleanup`
`docs/`	Documentation changes	`docs/update-api-readme`
`test/`	Test-only changes	`test/add-password-reset-tests`
`ci/`	CI/CD workflow or pipeline changes	`ci/update-github-actions`
`devops/`	Infrastructure, environment, deployment, or operational changes	`devops/add-staging-env-var`
`hotfix/`	Critical production fixes	`hotfix/production-login-failure`

8.2 Branch naming examples

Good examples:

feature/user-invite-flow
fix/mobile-login-layout
chore/update-node-version
refactor/payment-service-validation
devops/add-staging-secret

Bad examples:

changes
fix
stuff
john-branch
final-final-fix

9. Standard Development Flow

9.1 Starting work

Confirm that a valid ticket exists according to the Ticket Management SOP.
Confirm the ticket is clear enough to start.
Update local development.
Create a working branch from development.
Use a clear branch prefix and descriptive branch name.
Move the ticket to the appropriate active status.

9.2 Opening a Pull Request

Push the working branch to GitHub.
Open a Pull Request targeting development.
Complete the GitHub PR template and checklist.
Link the related ticket.
Request review according to the Pull Request SOP.

9.3 Merging into development

Ensure the PR has the required approval.
Ensure required checks are passing.
Ensure review comments are addressed.
Merge the PR into development.
Confirm the automatic development deployment succeeds or report any failure.
Update the related ticket according to the Ticket Management SOP.

10. Environment Promotion Flow

10.1 Development environment

Mandatory Changes merged into development are automatically deployed to the development environment.

The development environment is used for early integration validation and internal verification.

The PR author or responsible team should confirm that the automatic deployment completed successfully.

10.2 Staging environment

Default Staging deployment is manual and should happen only when the responsible individual or team decides that the change is ready for staging verification.

QA or the responsible individual/team may deploy an approved version from the corresponding branch to staging.

Staging is used for QA verification, release candidate testing, and validation before production promotion.

The responsible individual/team may deploy the latest version or a historical version to staging when needed.

10.3 Production environment

Mandatory Production deployment may happen only after QA or the responsible individual/team confirms that the relevant changes are acceptable for production.

To prepare production code, the responsible individual/team creates a Pull Request from development into main.

Once the PR into main is approved and merged, the responsible individual/team may manually deploy the approved version to production.

The responsible individual/team may deploy the latest version or a historical version from main to production when needed.

11. Pull Requests into main

11.1 When to create a PR into main

Mandatory A PR into main should be created only when the relevant changes in development are approved for production.

Before opening a PR into main, confirm that:

required PRs have been merged into development,
the relevant version has been deployed to staging when needed,
QA or the responsible individual/team has approved the changes,
known risks are documented,
and the production deployment owner is clear.

11.2 What the PR into main should contain

A PR into main should clearly describe what is being promoted to production.

The PR description should include:

summary of included changes,
related tickets or PRs,
QA or verification status,
known risks or limitations,
deployment notes,
and rollback notes when applicable.

11.3 Merging into main

A PR into main may be merged only when:

the PR is approved,
required checks pass,
QA or the responsible individual/team confirms production readiness,
the production deployment owner is clear,
and there are no unresolved blocking concerns.

12. Direct Commits and Rule Bypass

Mandatory Direct commits to development or main are not allowed during normal work.

Branch protection, repository rules, and Pull Request review requirements should be used to enforce this workflow whenever possible.

12.1 Critical exceptions

Direct commits, emergency merges, or rule bypasses may be allowed only in critical situations.

Examples:

critical production incident,
broken deployment pipeline requiring immediate repair,
security emergency,
repository configuration issue blocking all normal work,
or other time-sensitive operational emergency.

12.2 Documentation required for bypass

If normal branch or PR rules are bypassed, the responsible person must document:

what was bypassed,
why it was necessary,
who approved it,
what was changed,
what risks were accepted,
and what follow-up work is required.

A ticket must be created or updated as soon as possible after the emergency action.

13. Hotfixes

13.1 Default hotfix path

Default Hotfixes should still follow the normal branch and Pull Request process whenever possible.

The preferred hotfix flow is:

hotfix branch from development → PR into development → validation → PR into main → production deployment

This keeps development and main aligned and avoids fixing production in a way that is later lost or overwritten.

13.2 Emergency hotfix exception

In a critical production emergency, an authorized person may approve a faster path.

If a faster path is used, the change must still be brought back into development as soon as possible.

The emergency action must be documented in the related ticket and PR.

14. No Release Branches

Mandatory Release branches are not used in this workflow at this time.

The current workflow intentionally uses only:

main,
development,
and short-lived working branches.

Release branches may be introduced later if the organization needs more complex release management.

15. Version and Historical Deployments

Default The responsible individual or team may deploy either the latest version or a historical version to staging or production when needed.

Historical deployments may be useful for:

rollback,
reproducing an issue,
validating a previous release candidate,
or restoring a known good version.

Historical deployments should be documented clearly, including the branch, commit, tag, or version deployed.

16. Procedure

16.1 Creating a working branch

Confirm that a valid ticket exists.
Update local development.
Create a working branch from development.
Use a clear branch prefix and descriptive branch name.
Start implementation.

16.2 Merging work into development

Open a PR from the working branch into development.
Complete the PR template and checklist.
Request review according to the Pull Request SOP.
Address review comments.
Ensure required checks pass.
Merge into development.
Confirm the automatic development deployment.
Update the related ticket.

16.3 Deploying to staging

Confirm the relevant change exists in development.
Confirm the change is ready for staging verification.
Manually deploy the selected version to staging.
Document the deployed version when needed.
Move related tickets to the appropriate QA status when applicable.

16.4 Promoting to production

Confirm QA or responsible individual/team approval.
Create a PR from development into main.
Describe the included changes and related tickets.
Document known risks and deployment notes.
Review and approve the PR.
Merge the PR into main.
Manually deploy the selected version from main to production.
Perform post-deployment verification according to the Deployment SOP.

17. Exceptions

17.1 Critical production incidents

Critical production incidents may require an accelerated path.

Even in this case:

a ticket must exist or be created as soon as possible,
the change must be traceable,
the reason for bypassing the normal process must be documented,
and the change must be reconciled back into development if needed.

the related ticket is linked or updated,
the working branch was created from the correct base branch,
the PR targets the correct branch,
the PR is reviewed and merged according to the Pull Request SOP,
the automatic development deployment succeeds after merge to development,
staging deployment is completed when required,
QA or responsible individual/team approval exists before production promotion,
production changes are merged into main before production deployment,
and any exceptions or bypasses are documented.

19. Short Checklist

19.1 Before creating a branch

Ticket exists.
Ticket is clear enough to start.
Local development is up to date.
Branch will be created from development.
Branch name uses a clear prefix and description.

19.2 Before opening a PR

PR targets development.
PR is linked to a valid ticket.
PR follows the Pull Request SOP.
PR contains one ticket or one logical unit of work.
Unrelated changes are not included.

19.3 Before merging into development

Required approval exists.
Required checks pass.
Review comments are addressed.
PR targets development.
Related ticket is updated.

19.4 Before deploying to staging

Selected version exists in development.
Responsible individual/team is clear.
Deployment target is clear.
Related tickets are ready for QA or verification.
Version deployed is documented when needed.

19.5 Before merging into main

QA or responsible individual/team approval exists.
Included changes are understood.
Known risks are documented.
Production deployment owner is clear.
PR from development into main is created.

19.6 Before deploying to production

PR into main is merged.
Selected production version is clear.
Responsible individual/team is available.
Rollback or recovery approach is understood when applicable.
Post-deployment verification is planned.

20. Workflow Diagram

20.1 Standard Git flow

flowchart TD
  A[Ticket Exists] --> B[Create Working Branch from development]
  B --> C[Implement Change]
  C --> D[Open PR into development]
  D --> E[Review PR]
  E --> F{Approved and Checks Passing?}
  F -- No --> G[Author Updates PR]
  G --> E
  F -- Yes --> H[Merge into development]
  H --> I[Automatic Deploy to Development Environment]
  I --> J{Ready for Staging?}
  J -- No --> K[Continue Work or Wait]
  J -- Yes --> L[Manual Deploy to Staging]
  L --> M[QA or Responsible Team Verification]
  M --> N{Approved for Production?}
  N -- No --> O[Fix Issues in Working Branch]
  O --> D
  N -- Yes --> P[Create PR from development to main]
  P --> Q[Review Production PR]
  Q --> R{Approved?}
  R -- No --> S[Resolve Blocking Concerns]
  S --> Q
  R -- Yes --> T[Merge into main]
  T --> U[Manual Deploy to Production]
  U --> V[Post-Deployment Verification]

20.2 Emergency exception flow

flowchart TD
  A[Critical Situation Identified] --> B[Create or Update Ticket]
  B --> C[Authorized Person Approves Exception]
  C --> D[Apply Emergency Change]
  D --> E[Document Reason and Risk]
  E --> F[Deploy or Restore Service]
  F --> G[Verify System]
  G --> H[Create Follow-Up Cleanup if Needed]
  H --> I[Reconcile Change Back to development]

21. Version History

Version	Date	Author	Changes
0.1	2026-06-08	Head of Engineering	Initial draft.
1.0	2026-06-10	Head of Engineering	Active.