Source Control & Branching

Threat model

Attackers and negligent insiders exploit workflow gaps: pushing directly to main, hiding changes in stale release branches, or merging without CI evidence. Long-lived branches diverge from production reality—security fixes on main never reach a six-month-old release/2.4 branch until a painful merge conflict invites shortcuts.

Solution: trunk-based with feature flags

Merge incomplete work behind feature flags instead of hoarding it on a branch. Every commit on main must pass CI; deploy pipelines read flag state at runtime. This collapses integration risk and ensures security scanners run on the code that actually ships.

flowchart LR
  subgraph dev["Developer"]
    F["feature/auth-mfa\n< 48h lifetime"]
  end
  subgraph trunk["Protected main"]
    M["main\nalways green"]
  end
  subgraph cd["Continuous delivery"]
    CI["CI + security gates"]
    DEP["Deploy to staging"]
    FF["Feature flag OFF"]
  end
  F -->|"PR + review"| M
  M --> CI --> DEP
  DEP --> FF
  FF -->|"flag ON"| PROD["Production traffic"]

Platform automation: enforce short-lived branches

Stale branch cleanup and PR size limits reduce review fatigue—a social engineering vector where rushed reviewers approve oversized diffs. Automate reminders and block merges when branches exceed age or line-count thresholds.

name: Stale branch hygiene
on:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v9
        with:
          stale-branch-message: |
            This branch has had no commits for 14 days.
            Trunk-based policy: rebase or close. Security fixes land on main only.
          days-before-branch-stale: 14
          days-before-branch-delete: 7
          ignore-branches: main,release/**

stale-branches:
  stage: maintenance
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - |
      curl --request DELETE \
        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/branches?search=feature/" \
        | jq '.[] | select(.commit.committed_date < (now - 1209600)) | .name'

$ git switch main && git pull --ff-only
$ git switch -c feature/pay-4821-mfa
# small, focused change; flag guards incomplete UI
$ git commit -m "feat(auth): add TOTP verify behind flag mfa_beta"
$ git push -u origin feature/pay-4821-mfa
$ gh pr create --base main --title "feat(auth): MFA TOTP (flagged)"
→ CI runs SAST/SCA before human review; never push directly to main

Threat model

• Credential compromise — leaked GITHUB_TOKEN or personal access token with write access
• Force-push history rewrite — attacker removes evidence of malicious commits
• Admin bypass — repo owners merging without review during "emergency"
• Unsigned commits — impersonation; no cryptographic proof of author identity
• Missing status checks — merge before SAST/secret scan completes

Solution: defense-in-depth rules

flowchart TD
  PUSH["git push origin feature/x"] --> PR["Open pull request"]
  PR --> CI["Required CI checks\nbuild · test · SAST · secrets"]
  PR --> REV["≥ 2 approvals\nCODEOWNERS satisfied"]
  PR --> SIG{"Signed commits?"}
  SIG -->|no| BLOCK1["❌ Merge blocked"]
  SIG -->|yes| GATE{"All gates green?"}
  CI --> GATE
  REV --> GATE
  GATE -->|no| BLOCK2["❌ Merge blocked"]
  GATE -->|yes| MERGE["✅ Merge to main"]
  MERGE --> AUDIT["Immutable audit log\n+ provenance for CI"]

Infrastructure as code: branch rules

Manual UI configuration drifts across hundreds of repos. Encode branch protection in Terraform or a central policy repo so every new service inherits the same security baseline.

{
  "pattern": "main",
  "required_status_checks": {
    "strict": true,
    "contexts": ["ci/build", "security/sast", "security/gitleaks"]
  },
  "required_pull_request_reviews": {
    "required_approving_review_count": 2,
    "require_code_owner_reviews": true,
    "dismiss_stale_reviews": true
  },
  "require_signed_commits": true,
  "enforce_admins": true,
  "required_linear_history": true,
  "restrictions": null
}

branch_rules:
  - name: main
    branch_name: main
    protected: true
    push_access_level: no_one
    merge_access_level: developer
    allow_force_push: false
    code_owner_approval_required: true
    approvals_required: 2
    status_checks:
      - name: unit-tests
      - name: sast
      - name: secret_detection
    commit_committer_check: true
    reject_unsigned_commits: true

Threat model

Vague commits hide security-relevant changes: a dependency bump smuggled into "misc cleanup," or a credential rotation buried in a mega-commit. Unsigned commits allow author spoofing—git config user.email is trivially forgeable without GPG or SSH signing verification.

Conventional Commits format

Solution: enforce at commit and CI time

Local enforcement via commit-msg hooks catches mistakes before push. CI validates the PR title and squash commit message—release automation (semantic-release, release-please) depends on parseable history.

name: Commit standards
on:
  pull_request:
    types: [opened, edited, synchronize]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          types: |
            feat
            fix
            security
            chore
            docs
          requireScope: true
      - name: Verify signed commits
        run: |
          gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/commits \
            --jq '.[] | select(.commit.verification.verified == false) | .sha' \
            | tee /tmp/unsigned.txt
          test ! -s /tmp/unsigned.txt

commitlint:
  stage: validate
  image: node:20-alpine
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - npm install -g @commitlint/cli @commitlint/config-conventional
  script:
    - |
      npx commitlint --from="$CI_MERGE_REQUEST_DIFF_BASE_SHA" --to="$CI_COMMIT_SHA" --verbose
  allow_failure: false

SSH commit signing setup

$ ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/signing_key -N ""
$ git config --global gpg.format ssh
$ git config --global user.signingkey ~/.ssh/signing_key.pub
$ git config --global commit.gpgsign true
# Upload ~/.ssh/signing_key.pub to GitHub → Settings → SSH keys → Signing key
$ git commit -S -m "feat(payments): add idempotency key header"
→ GitHub shows "Verified" badge; branch protection can require it

Threat model

• Self-approval — author merges own PR with a second account or admin rights
• Review fatigue — 2,000-line diffs approved in minutes; LGTM without reading
• CODEOWNERS bypass — missing owners file; security team never notified on auth changes
• Malicious dependency PR — typosquat package or lockfile manipulation hidden in generated files
• CI workflow injection — PR modifies .github/workflows/ to exfiltrate secrets

Solution: structured review with ownership

# Default owners
*                           @acme/platform-team

# Security-sensitive paths — require security + domain owner
/src/auth/                  @acme/security-team @acme/identity-squad
/src/payments/              @acme/security-team @acme/payments-squad
/infra/                     @acme/platform-team @acme/security-team
/.github/workflows/         @acme/platform-team
/terraform/                 @acme/platform-team @acme/security-team

# Dependencies — lockfile changes need explicit review
package-lock.json           @acme/security-team @acme/frontend-leads
go.sum                      @acme/security-team @acme/backend-leads

sequenceDiagram
  participant Dev as Developer
  participant PR as Pull Request
  participant CI as CI Security
  participant CO as CODEOWNERS
  participant Sec as Security reviewer
  participant Main as protected main
  Dev->>PR: Open PR (+ template checklist)
  PR->>CI: Trigger SAST, SCA, gitleaks
  CI-->>PR: SARIF annotations inline
  PR->>CO: Request reviews auto-assigned
  CO->>Sec: Notify on /auth/ changes
  Sec->>PR: Approve with security sign-off
  PR->>Main: Merge (2 approvals + green CI)

PR template for security attestation

## Summary
<!-- What changed and why -->

## Security checklist
- [ ] No secrets, tokens, or PII in diff
- [ ] User input validated and parameterized (SQL, shell, path)
- [ ] AuthZ checked on new endpoints (not authN alone)
- [ ] Dependencies pinned; no unreviewed major bumps
- [ ] Threat model updated if attack surface changed

## Test evidence
- [ ] Unit tests added/updated
- [ ] SAST/SCA checks green

## Security review (required for ~security ~auth labels)

### Data classification
- [ ] No regulated data (PCI/PHI) in logs
- [ ] Encryption at rest/transit unchanged or improved

### Access control
- [ ] Least-privilege IAM / RBAC for new resources
- [ ] Service accounts scoped to single purpose

### Dependency changes
- [ ] Lockfile diff reviewed line-by-line
- [ ] No new unpinned git:// or http:// sources

/label ~security-review-required

Threat model

Developers paste AWS keys into config files, commit .env by mistake, or add id_rsa during a hurried debug session. Bots scan GitHub within minutes of public exposure. Even private repos leak via misconfigured Actions logs, support tickets, or departed employee laptops.

Solution: layered local enforcement

pre-commit framework configuration

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks
        args: [--verbose, --redact]

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: detect-private-key
      - id: check-added-large-files
        args: [--maxkb=500]
      - id: check-merge-conflict
      - id: no-commit-to-branch
        args: [--branch, main]

  - repo: https://github.com/bridgecrewio/checkov
    rev: 3.2.238
    hooks:
      - id: checkov
        args: [--framework, terraform, --quiet]

  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.27.0
    hooks:
      - id: commitizen
        stages: [commit-msg]

$ pip install pre-commit
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ pre-commit install --hook-type commit-msg
$ pre-commit run --all-files
gitleaks.............................................................Passed
$ git commit -m "feat(api): add webhook handler"
→ hooks run on staged files only; fast feedback < 10s typical

CI backstop: hooks can be skipped

git commit --no-verify bypasses local hooks. CI must re-run the same checks. Mirror pre-commit config in the pipeline for deterministic, auditable enforcement.

name: Pre-commit CI
on: [pull_request, push]
jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pre-commit
      - run: pre-commit run --all-files --show-diff-on-failure
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

include:
  - template: Security/Secret-Detection.gitlab-ci.yml

pre-commit:
  stage: test
  image: python:3.12-slim
  script:
    - pip install pre-commit
    - pre-commit run --all-files --show-diff-on-failure
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

secret_detection:
  stage: test
  variables:
    SECRET_DETECTION_HISTORIC_SCAN: "true"

Threat model

• Blast radius expansion — one compromised CI token in a monorepo builds every service
• Dependency confusion — polyrepo internal packages published without namespace controls
• Inconsistent security baselines — polyrepo repos missing branch protection or pre-commit
• Shadow dependencies — monorepo teams import across boundaries without CODEOWNERS review
• Over-broad access — all engineers clone entire monorepo including regulated components

Comparison matrix

flowchart TB
  subgraph mono["Monorepo push"]
    PUSH["push to main"]
    PATH["path filter:\nservices/payments/**"]
    PAY["payments CI only"]
    SKIP["skip 40 other services"]
  end
  PUSH --> PATH
  PATH --> PAY
  PATH --> SKIP
  subgraph poly["Polyrepo push"]
    P2["push payments-service repo"]
    P2CI["payments pipeline only\nnarrow OIDC role"]
  end
  P2 --> P2CI

Solution: path-filtered CI with OIDC scoping

Monorepos require affected builds and path filters so a docs change does not trigger production deploys for unrelated services. OIDC trust policies should include path-based subject claims where the platform supports it.

name: payments-service
on:
  pull_request:
    paths:
      - "services/payments/**"
      - "libs/payments-sdk/**"
      - ".github/workflows/payments-service.yml"
  push:
    branches: [main]
    paths:
      - "services/payments/**"
      - "libs/payments-sdk/**"
permissions:
  contents: read
  id-token: write
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            payments:
              - "services/payments/**"
              - "libs/payments-sdk/**"
      - if: steps.filter.outputs.payments == 'true'
        run: echo "Build payments only — OIDC role arn:aws:iam::123:role/gh-payments"

payments-build:
  stage: build
  rules:
    - changes:
        - services/payments/**/*
        - libs/payments-sdk/**/*
  script:
    - cd services/payments && npm ci && npm test && npm run build

auth-build:
  stage: build
  rules:
    - changes:
        - services/auth/**/*
  script:
    - cd services/auth && go test ./...

# Polyrepo alternative: separate GitLab projects with shared CI template
include:
  - project: platform/ci-templates
    file: /security-pipeline.yml

Polyrepo: org-level policy consistency

Without centralized templates, polyrepo sprawl means repo #47 still lacks signed commits. Use golden pipeline templates, org rulesets, and internal Terraform modules for repo creation that apply branch protection, pre-commit, and CODEOWNERS scaffolding automatically.

$ npx nx affected -t test,lint,build --base=origin/main
NX   Running targets test, lint, build for 2 projects:
- payments-api
- payments-sdk
$ npx nx graph --affected
→ CI runs only impacted projects; security scans scoped to affected artifacts