Branching strategy (dev / qa / main)

Overview

The eigenoid org uses a three-branch model: dev is the active integration branch, qa is the pre-release validation gate, and main holds the production-ready code. All feature work targets dev; promotion to qa and then to main is controlled by dedicated CI gate workflows that enforce branch order and block out-of-sequence merges. For the rationale behind this model, see ADR-0021.

Which repos use this model

Repos governed by this model are identified by the GitHub custom property branch_strategy=dev-qa-main. Currently enrolled:

• eigenoid/eigenoid
• eigenoid/eigenoid-sample

The svc-* and app-* repos follow the same three-branch promotion flow but are governed by separate org-level rulesets that match on repository name patterns directly (PR #67, targeting svc-* and app-* names). They do not rely on the branch_strategy custom property, so they will not appear in property-filtered queries or be affected by the custom-property-based config changes introduced in E3.

Day-to-day workflow

1. Branch off dev:

   git checkout -b feat/<issue>-short-description dev

   bash
2. Open a PR targeting dev. CI runs the full check suite on every push.
3. Once merged to dev, a maintainer opens the dev → qa promotion PR. The promotion-gate-qa workflow validates that the source branch is dev and fails any other source.
4. After QA validation, a maintainer opens the qa → main promotion PR. The promotion-gate-main workflow validates that the source branch is qa.

What happens if you PR against main directly

The promotion-gate CI workflow will fail the check. Redirect the PR to target dev instead. This applies to both qa and main — neither accepts feature branches as a direct merge source.

Repo default branch

All enrolled repos have dev set as their default branch. Cloning gives you dev automatically — no additional configuration is required.

git clone git@github.com:eigenoid/<repo>.git
# Already on dev

bash

See also

• ADR-0021: dev/qa/main branching strategy — decision record and full rationale
• Onboarding guide — first steps for new contributors

Maintainer Notes

• Workflow trigger audits: Workflows that reference github.event.repository.default_branch may change behavior now that dev is the default branch. Audit any release or deploy steps and anchor them explicitly to refs/heads/main rather than relying on the default-branch value.
• Deploy workflows: New PRs will default to targeting dev. Deploy workflows watching main continue to work correctly; they only fire on promotion merges to main, which is the intended behavior.