Enterprise Readiness

Enterprise Readiness Assessment

Production/enterprise tier only — see references/tier-framing.md.

When to Use

• Production/enterprise readiness evaluations
• Supply chain security: SLSA provenance, cosign signing, SBOMs
• CI/CD hardening, workflow permissions
• OpenSSF Best Practices (Passing/Silver/Gold), OSPS Baseline (L1/2/3)
• Scorecard optimization (Token-Permissions, Branch-Protection, Pinned-Deps)
• Code review, ADRs, changelogs, SECURITY.md

Assessment Workflow

1. Discovery: Identify platform, languages, existing CI/CD, dependabot.yml 2. Scoring: Apply checklists; check Scorecard, badge criteria, coverage 3. Gap Analysis: List missing controls by severity 4. Implementation: Apply fixes (SHA-pin actions, harden permissions, add workflows) 5. Verification: Re-score and compare

Mandatory Workflows & Badges

Required coverage: CI, CodeQL, Scorecard, dependency review, composer audit, SBOM — as dedicated workflows or jobs calling the netresearch reusable. Badges: CI, Codecov, Scorecard, Best Practices, Baseline. See references/badges-and-workflows.md.

Key Hardening Patterns

• Permissions: Declare permissions: contents: read at workflow-level; grant write only per-job
• SHA pinning: Third-party actions pinned to SHA with version comment (# v4.2.0). Org-internal reusable workflows use @main
• Harden-Runner: step-security/harden-runner as first step in every job; prefer egress-policy: block with allowed-endpoints
• Dependabot: Configure dependabot.yml with all ecosystems (composer, npm, github-actions, docker); set up auto-merge workflow for dependency PRs using pull_request_target
• Coverage: Upload via codecov-action; configure codecov.yml with patch coverage threshold
• Duplicate CI prevention: Scope push: trigger to branches: [main] when pull_request: is also present
• SLSA provenance: Use actions/attest-build-provenance with id-token: write and attestations: write permissions; verify with gh attestation verify
• Security policy: Create SECURITY.md with vulnerability disclosure process and response SLA (Critical: 7 days, High: 30 days)

Critical Rules

• NEVER interpolate ${{ github.event.* }} or ${{ inputs.* }} in run: blocks (script injection)
• NEVER guess action versions -- fetch from GitHub API and verify SHA against tags
• ALWAYS include https:// URLs in badge justifications
• ALWAYS configure auto-merge for repos with Dependabot/Renovate

References

Related skills: go-development, github-project, security-audit, git-workflow.

Two-Factor Authentication Enforcement Guide

OpenSSF Gold Badge requirements: require_2FA, secure_2FA

>

Projects must require 2FA for contributors with commit/accept rights

and encourage secure 2FA methods (hardware tokens, TOTP).

GitHub Organization 2FA

Enable Organization-Wide 2FA Requirement

1. Go to Organization Settings → Security → Authentication security 2. Enable Require two-factor authentication 3. Set grace period for existing members (recommended: 7 days)

Settings → Security → Authentication security
☑️ Require two-factor authentication for everyone in the organization

Verify Member Compliance

# List members without 2FA (requires admin)
gh api orgs/YOUR_ORG/members --jq '.[] | select(.two_factor_disabled == true) | .login'

# Organization security overview
gh api orgs/YOUR_ORG --jq '{
  members: .members_with_two_factor_disabled,
  total: .members_count
}'

Repository-Level Protection

Branch Protection with 2FA

# Recommended branch protection settings
branch_protection:
  required_status_checks:
    strict: true
    contexts: ["ci", "security"]
  enforce_admins: true
  required_pull_request_reviews:
    dismiss_stale_reviews: true
    require_code_owner_reviews: true
    required_approving_review_count: 1
  # Note: GitHub enforces org-level 2FA requirement

Commit Signing (Additional Security)

2FA protects account access; commit signing protects commit integrity:

# Configure GPG signing
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_KEY_ID

# Or use SSH signing (requires 2FA to add key)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub

Secure 2FA Methods

Recommended (Gold Badge: secure_2FA)

Not Recommended

Documentation Requirements

SECURITY.md Section

Add to your SECURITY.md:

## Contributor Security Requirements

### Two-Factor Authentication

All contributors with commit access MUST enable two-factor authentication (2FA).

**Required for:**
- Repository administrators
- Contributors with write access
- Code owners
- Release managers

**Recommended 2FA methods:**
1. Hardware security keys (YubiKey, Titan Key)
2. TOTP authenticator apps (not SMS)
3. Passkeys/Platform authenticators

**Setup instructions:**
- [GitHub 2FA Setup](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)
- [Hardware Key Setup](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key)

### Commit Signing

We encourage (but do not require) GPG or SSH signed commits.
See [Signing Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification).

CONTRIBUTING.md Section

## Security Requirements

Before your first contribution:

1. **Enable 2FA** on your GitHub account
   - Required for all contributors with commit access
   - Recommended: Hardware security key or authenticator app
   - [Setup Guide](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)

2. **Optional: Sign your commits**
   - GPG signing provides non-repudiation
   - [Signing Guide](https://docs.github.com/en/authentication/managing-commit-signature-verification)

Verification Workflow

Check 2FA Status in CI

# .github/workflows/security-check.yml
name: Security Compliance
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  check-contributor:
    runs-on: ubuntu-latest
    steps:
      - name: Check PR author 2FA (informational)
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Note: 2FA status not directly available via API
          # Organization-level 2FA requirement is the enforcement mechanism
          echo "✅ PR from ${{ github.actor }}"
          echo "ℹ️ 2FA enforcement is handled at organization level"

Organization Audit

#!/bin/bash
# scripts/audit-2fa.sh

ORG="your-org"

echo "=== 2FA Compliance Audit ==="

# Check org 2FA requirement
REQUIRED=$(gh api orgs/$ORG --jq '.two_factor_requirement_enabled')
echo "2FA Required: $REQUIRED"

if [ "$REQUIRED" = "true" ]; then
    echo "✅ Organization requires 2FA"
else
    echo "❌ Organization does NOT require 2FA"
    echo "Action: Enable at Settings → Security → Authentication security"
fi

# List admins (should all have 2FA if org requires it)
echo ""
echo "Repository Admins (all should have 2FA):"
gh api repos/$ORG/REPO/collaborators --jq '.[] | select(.permissions.admin == true) | .login'

Badge Criteria Alignment

Solo Maintainer Considerations

For solo maintainers who cannot enforce organization-level 2FA:

## 2FA Statement (Solo Maintainer)

This project is maintained by a single developer.

**2FA Status:**
- ✅ Maintainer uses hardware security key (YubiKey)
- ✅ Backup codes stored securely offline
- ✅ Recovery email protected with 2FA

**For future contributors:**
- 2FA will be required before granting write access
- Hardware keys or authenticator apps recommended

Resources

• GitHub 2FA Documentation
• FIDO Alliance - Security Keys
• OpenSSF Badge 2FA Criteria
• NIST Digital Identity Guidelines

OpenSSF Badge Display Guide

MANDATORY Badge Requirements

ALL badges in this document are MANDATORY, not optional.

Every project MUST have these badges displayed in README.md:

"Unknown" or placeholder badges are NOT acceptable. Fix them immediately.

---

OpenSSF Silver Badge requirement: documentation_achievements

>

Projects MUST display their OpenSSF Best Practices Badge prominently in the README.

Badge URLs

Get Your Badge (MANDATORY STEPS)

1. Register at https://www.bestpractices.dev/ 2. Complete criteria for your target level 3. Copy badge URL from your project page

Badge Formats

# Markdown (Recommended for README.md)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/YOUR_PROJECT_ID/badge)](https://www.bestpractices.dev/projects/YOUR_PROJECT_ID)

# HTML
<a href="https://www.bestpractices.dev/projects/YOUR_PROJECT_ID">
  <img src="https://www.bestpractices.dev/projects/YOUR_PROJECT_ID/badge" alt="OpenSSF Best Practices">
</a>

# reStructuredText (for Python docs)
.. image:: https://www.bestpractices.dev/projects/YOUR_PROJECT_ID/badge
   :target: https://www.bestpractices.dev/projects/YOUR_PROJECT_ID
   :alt: OpenSSF Best Practices

Badge Levels

OSPS Baseline Badge (Levels 1/2/3 — separate badge, same project):

[![OpenSSF Baseline](https://www.bestpractices.dev/projects/PROJECT_ID/baseline)](https://www.bestpractices.dev/projects/PROJECT_ID)

The Baseline badge shows the achieved OSPS security level (1, 2, or 3). Both badges should be displayed together.

README Badge Section

Recommended Placement

# Project Name

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/ID/badge)](https://www.bestpractices.dev/projects/ID)
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/ID/baseline)](https://www.bestpractices.dev/projects/ID)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ORG/REPO/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ORG/REPO)
[![Go Report Card](https://goreportcard.com/badge/github.com/ORG/REPO)](https://goreportcard.com/report/github.com/ORG/REPO)
[![License](https://img.shields.io/github/license/ORG/REPO)](LICENSE)

Project description here...

Complete Badge Row Example

<!-- Recommended badge order: Security → Quality → Build → License -->
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/ID/badge)](https://www.bestpractices.dev/projects/ID)
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/ID/baseline)](https://www.bestpractices.dev/projects/ID)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ORG/REPO/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ORG/REPO)
[![Security Audit](https://img.shields.io/badge/security-audited-green)](SECURITY.md)
[![codecov](https://codecov.io/gh/ORG/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/ORG/REPO)
[![Go Report Card](https://goreportcard.com/badge/github.com/ORG/REPO)](https://goreportcard.com/report/github.com/ORG/REPO)
[![CI](https://github.com/ORG/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/ORG/REPO/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/ORG/REPO)](LICENSE)

Additional Security Badges

OpenSSF Scorecard

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ORG/REPO/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ORG/REPO)

SLSA Provenance Level

[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)

Sigstore Signed

[![Sigstore](https://img.shields.io/badge/sigstore-signed-blue)](https://search.sigstore.dev/?hash=SHA256_HASH)

Security Policy

[![Security Policy](https://img.shields.io/badge/security-policy-blue)](SECURITY.md)

Badge Verification

Automated Badge Check

# .github/workflows/verify-badges.yml
name: Verify Badges
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly
  workflow_dispatch:

jobs:
  check-badges:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check OpenSSF Badge Status
        run: |
          # Use cache-buster to avoid stale responses
          DATA=$(curl -s "https://www.bestpractices.dev/projects/YOUR_ID.json?_=$(date +%s)")
          STATUS=$(echo "$DATA" | jq -r '.badge_level')
          echo "Current badge level: $STATUS"
          if [ "$STATUS" = "passing" ] || [ "$STATUS" = "silver" ] || [ "$STATUS" = "gold" ]; then
            echo "✅ Badge status valid"
          else
            echo "❌ Badge status issue"
            exit 1
          fi

      - name: Check Scorecard
        run: |
          SCORE=$(curl -s "https://api.securityscorecards.dev/projects/github.com/ORG/REPO" | jq -r '.score')
          echo "Scorecard score: $SCORE"

Badge Link Validator

#!/bin/bash
# scripts/verify-badge-links.sh

echo "Checking badge links in README.md..."

# Extract all badge URLs
BADGES=$(grep -oP 'https://[^)]+badge[^)]*' README.md)

for URL in $BADGES; do
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
    if [ "$STATUS" = "200" ]; then
        echo "✅ $URL"
    else
        echo "❌ $URL (HTTP $STATUS)"
        EXIT_CODE=1
    fi
done

exit ${EXIT_CODE:-0}

Tracking Progress

Progress Badge

For projects working toward a badge level:

<!-- Show progress toward Silver -->
[![OpenSSF Progress](https://img.shields.io/badge/OpenSSF-85%25%20toward%20Silver-yellow)](https://www.bestpractices.dev/projects/ID)

Criteria Checklist in README

## OpenSSF Best Practices Progress

- [x] Passing Level (100%)
- [x] Security policy documented
- [x] Signed releases
- [ ] Silver Level (85%)
  - [x] DCO enforcement
  - [x] 80% test coverage
  - [ ] Two-person review (solo maintainer)
- [ ] Gold Level (40%)
  - [ ] 90% test coverage
  - [ ] Security audit

Badge Criteria Alignment

Resources

• OpenSSF Best Practices Badge
• OSPS Baseline Standard
• OpenSSF Scorecard
• Shields.io Custom Badges
• SLSA Badge Generator

Badge Data Submission Guide

Practical guide for programmatically submitting OpenSSF Best Practices Badge data.

Overview

The bestpractices.dev platform uses a Rails web application. There is no official REST API for updating badge criteria. Submissions are done via authenticated HTML form PATCH requests.

Submission Script

A Python script can automate badge data submission using session cookies:

#!/usr/bin/env python3
"""Submit OpenSSF Best Practices Badge data.

Usage:
    BADGE_COOKIE='...' python3 submit-badge.py [--dry-run] [--level LEVEL]
"""
import json
import os
import re
import sys
import time
import http.cookiejar
import urllib.parse
import urllib.request

COOKIE_NAME = '_BadgeApp_session'
PROJECT_ID = 12345  # Replace with your project ID
BASE_URL = 'https://www.bestpractices.dev'

AUTH_TOKEN_PATTERN = re.compile(
    r'<input type="hidden" name="authenticity_token" value="([^"]+)"'
)
CSRF_TOKEN_PATTERN = re.compile(
    r'<meta name="csrf-token" content="([^"]+)"'
)

LEVELS = ['passing', 'silver', 'gold', 'baseline-1', 'baseline-2', 'baseline-3']

Authentication

1. Log in to bestpractices.dev in your browser 2. Extract the _BadgeApp_session cookie value from browser DevTools 3. Pass it via environment variable OR file (file recommended due to shell quoting issues):

# RECOMMENDED: Read from file to avoid shell quoting issues with special chars
cookie_file = '/tmp/badge-cookie.txt'
if os.path.exists(cookie_file):
    with open(cookie_file) as f:
        cookie = f.read().strip()
else:
    cookie = os.environ.get('BADGE_COOKIE', '')

Submission Flow

For each level:

1. GET the edit page to obtain CSRF tokens and lock version 2. PATCH the level URL with form-encoded data

GET  /en/projects/{ID}/{level}/edit  → Extract authenticity_token + lock_version
PATCH /en/projects/{ID}/{level}      → Submit form data with tokens

IMPORTANT: The level path segment is required for ALL levels including passing. Use /en/projects/{ID}/passing/edit, NOT /en/projects/{ID}/edit.

---

Critical Gotchas

1. Cookie Handling - Do NOT URL-Decode, Use File

CRITICAL: The session cookie must be sent exactly as received from the browser. Do NOT URL-decode it.

RECOMMENDED: Write cookie to a file instead of passing via environment variable. Session cookies often contain +, /, =, and other characters that break shell quoting.

# BEST - read from file (no shell quoting issues)
cookie = open('/tmp/badge-cookie.txt').read().strip()

# OK - environment variable (beware of shell quoting)
cookie = os.environ.get('BADGE_COOKIE', '')

# WRONG - URL decoding breaks session authentication
cookie = urllib.parse.unquote(os.environ.get('BADGE_COOKIE', ''))

Symptom: Writes appear to succeed (302 redirect) but data is silently not persisted.

2. URL-Required Justifications

Many criteria require https:// URLs in the justification text. Without URLs, criteria show "Warning: URL required, but no URL found" even when status is "Met".

CRITICAL: Even with status "Met", an empty justification or one without URLs causes the criterion to show "Unknown required information, not enough for a badge" on the edit page. The API will still report the status as "Met", but the badge percentage will NOT count it.

Commonly affected criteria (require URLs in justification at ALL levels):

Rule of thumb: Always include at least one https:// URL in every justification text.

{
  "dco_justification": "DCO enforced via GitHub Actions: https://github.com/org/repo/blob/main/.github/workflows/dco.yml"
}

3. Auto-Detected Fields Cannot Be Set

These fields are auto-detected by the platform and cannot be set via form submission:

Attempting to submit these fields causes HTTP 400 errors.

Remove them from your badge data files before submission.

Note: These fields show as ? in the API but do NOT count against badge percentages.

4. API Response Caching - Use Correct URL Path

CRITICAL: The /en/projects/{ID}.json path (with locale prefix) returns aggressively cached data that can be stale for hours. The /projects/{ID}.json path (without locale) returns fresh data.

# WRONG - returns stale cached data
curl -s "https://www.bestpractices.dev/en/projects/PROJECT_ID.json"

# CORRECT - returns fresh data
curl -s "https://www.bestpractices.dev/projects/PROJECT_ID.json?_=$(date +%s)"

Symptom: After successful submission (302 redirect), the API still shows old values. Switching from /en/projects/ to /projects/ path immediately shows updated data.

5. OSPS Baseline Field Names

OSPS Baseline criteria use a different naming convention in HTML forms:

Pattern: All lowercase, hyphens and dots become underscores.

Note: OSPS criteria do NOT affect Passing/Silver/Gold badge percentages. They are a separate badge program (OSPS Baseline).

6. Session Cookie Rotation

The server rotates session cookies via Set-Cookie headers. Your script must use CookieJar to automatically track cookie updates:

def make_opener(cookie):
    """Create urllib opener with cookie jar and no-redirect handling."""
    cj = http.cookiejar.CookieJar()
    c = http.cookiejar.Cookie(
        version=0, name='_BadgeApp_session', value=cookie,
        port=None, port_specified=False,
        domain='www.bestpractices.dev', domain_specified=True,
        domain_initial_dot=False,
        path='/', path_specified=True,
        secure=True, expires=None, discard=True,
        comment=None, comment_url=None, rest={}, rfc2109=False,
    )
    cj.set_cookie(c)

    class NoRedirectHandler(urllib.request.HTTPErrorProcessor):
        def http_response(self, request, response):
            return response
        https_response = http_response

    return urllib.request.build_opener(
        urllib.request.HTTPCookieProcessor(cj),
        NoRedirectHandler,
    )

7. Rate Limiting

Add delays between level submissions to avoid rate limiting:

time.sleep(3)  # Wait 3 seconds between submissions

---

Lock Version Extraction

CRITICAL: The lock_version hidden field is required for successful saves. Without it, submissions may silently fail (302 redirect but no data persisted).

The HTML attribute order varies - sometimes name comes before value, sometimes after. Use a regex that handles both orderings:

# CORRECT - handles both attribute orderings
LOCK_VERSION_PATTERN = re.compile(
    r'(?:name="project\[lock_version\]"[^>]*value="([^"]*)"|'
    r'value="(\d+)"[^>]*name="project\[lock_version\]")'
)
match = LOCK_VERSION_PATTERN.search(html)
lock_version = (match.group(1) or match.group(2)) if match else None

# WRONG - only handles one attribute ordering
re.search(r'name="project\[lock_version\]"[^>]*value="([^"]*)"', html)

---

Detecting Insufficient Criteria

The badge edit page contains <img> elements with id="{criterion}_enough" that indicate whether each criterion meets badge requirements. Use this to find what's actually blocking the badge percentage:

# After fetching the edit page HTML:
all_enough = re.findall(r'<img[^>]*id="(\w+)_enough"[^>]*alt="([^"]+)"', html)
not_enough = [(name, alt) for name, alt in all_enough if 'not' in alt.lower() or 'Not' in alt]

for name, alt in not_enough:
    print(f"  {name}: {alt}")

Common "not enough" messages:

• "Not enough for a badge." — Status is "Unmet" or criteria not satisfied
• "Unknown required information, not enough for a badge." — Status is "Met" but justification

is empty or missing required URL

---

Badge Data File Format

Structure badge data as JSON files per level:

badge-data-passing.json
badge-data-silver.json
badge-data-gold.json
badge-data-baseline-1.json
badge-data-baseline-2.json
badge-data-baseline-3.json

Each file contains field name/value pairs:

{
  "criterion_name_status": "Met",
  "criterion_name_justification": "Explanation with https://github.com/org/repo/evidence"
}

Valid status values: Met, Unmet, N/A, ? (unknown)

Note: Some criteria only accept specific status values:

• dynamic_analysis_enable_assertions_status: Only Met, Unmet, ? (NOT N/A)
• access_continuity_status: Only Met, Unmet, ? (NOT N/A)
• bus_factor_status: Only Met, Unmet, ? (NOT N/A)
• contributors_unassociated_status: Only Met, Unmet, ? (NOT N/A)
• two_person_review_status: Only Met, Unmet, ? (NOT N/A)

---

Multi-Project Batch Submission

For submitting badge data across multiple projects, use a configuration dict:

PROJECTS = {
    'project-name': {
        'id': 12345,
        'levels': {
            'passing': '/path/to/badge-data-passing.json',
            'silver': '/path/to/badge-data-silver.json',
            'gold': '/path/to/badge-data-gold.json',
        }
    },
    # ... more projects
}

# Submit all
for name, config in PROJECTS.items():
    for level, data_file in config['levels'].items():
        if os.path.exists(data_file):
            submit_level(opener, config['id'], level, data_file)
            time.sleep(3)

---

Solo Maintainer Justification Patterns

For projects with a single maintainer, use these justification templates:

`two_person_review` (set to Met, N/A not allowed):

The project uses automated multi-reviewer workflow: GitHub Copilot code review + auto-approve
bot for solo maintainer. Branch protection requires passing CI + review approval.
See: https://github.com/org/repo/blob/main/.github/workflows/pr-quality-gates.yml

`bus_factor` (set to Met, N/A not allowed):

Bus factor managed through comprehensive documentation, CI automation, and organizational access.
Organization maintains access to all repositories. Backup maintainers have repository access
via GitHub organization membership: https://github.com/orgs/ORG/people

`access_continuity` (set to Met, N/A not allowed):

Access continuity ensured via GitHub organization. Multiple organization members have admin
access. Repository settings and credentials managed at organization level:
https://github.com/orgs/ORG/people

See also: references/solo-maintainer-guide.md

---

Verification

After submission, verify via API:

# Check badge level (use /projects/ NOT /en/projects/)
curl -s "https://www.bestpractices.dev/projects/PROJECT_ID.json?_=$(date +%s)" | \
  jq '{badge_level, badge_percentage_0, badge_percentage_1, badge_percentage_2}'

# badge_percentage_0 = Passing
# badge_percentage_1 = Silver
# badge_percentage_2 = Gold

To verify specific criteria are truly accepted (not just "Met" in API):

# Fetch edit page and check _enough indicators
html = fetch_edit_page(opener, project_id, level)
not_enough = re.findall(
    r'<img[^>]*id="(\w+)_enough"[^>]*alt="([^"]+)"',
    html
)
blockers = [(n, a) for n, a in not_enough if 'not' in a.lower()]

---

Troubleshooting

N/A Not Allowed on Certain Criteria

Some Silver/Gold criteria do not allow N/A status. Submitting N/A causes validation errors that silently prevent the entire save (form re-renders with 200 status).

Passing criteria that DON'T allow N/A:

• dynamic_analysis_enable_assertions (only Met/Unmet/?)

Silver criteria that DON'T allow N/A:

• access_continuity (MUST)
• bus_factor (MUST)

Gold criteria that DON'T allow N/A:

• contributors_unassociated (MUST)
• two_person_review (MUST)

Always check the edit form's radio buttons to verify which values are accepted.

Mandatory Badges & Workflows

Mandatory Badges

Mandatory Workflows

Scorecard Quick Wins

Branch Coverage Guide

OpenSSF Badge Criteria: test_branch_coverage80 (Gold - requires 80% branch coverage)

Understanding Branch vs Statement Coverage

Statement Coverage

Measures which lines of code are executed:

func Example(x int) string {
    if x > 0 {        // Line executed
        return "pos"  // Line executed OR not
    }
    return "neg"      // Line executed OR not
}

100% statement coverage = all lines executed at least once.

Branch Coverage (Decision Coverage)

Measures whether each decision point (if/else, switch) has been tested for all outcomes:

func Example(x int) string {
    if x > 0 {        // Branch: true AND false
        return "pos"
    }
    return "neg"
}

100% branch coverage = both x > 0 (true) AND x <= 0 (false) tested.

Why Branch Coverage Matters

Statement coverage can be 100% while missing critical paths:

func Process(a, b bool) {
    if a && b {
        // Critical path
    }
}

// This test achieves 100% statement coverage
func TestProcess(t *testing.T) {
    Process(true, true)  // Executes the if block
    Process(false, false) // Skips the if block
}
// But misses: (true, false) and (false, true) branches

---

Measuring Branch Coverage in Go

Native Go Coverage (Statement Only)

Go's built-in coverage tool measures statement coverage:

go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out  # Shows statement coverage

Approach 1: gocover-cobertura + XML Analysis

Convert Go coverage to Cobertura XML format:

# Install
go install github.com/boumenot/gocover-cobertura@latest

# Generate
go test -coverprofile=coverage.out -covermode=count ./...
gocover-cobertura < coverage.out > coverage.xml

Then analyze with tools that support branch metrics.

Approach 2: gocov + gocov-xml

# Install
go install github.com/axw/gocov/gocov@latest
go install github.com/AlekSi/gocov-xml@latest

# Generate
go test -coverprofile=coverage.out ./...
gocov convert coverage.out | gocov-xml > coverage.xml

Approach 3: Codecov Branch Analysis

Codecov can analyze branch coverage:

# .github/workflows/coverage.yml
- name: Run tests
  run: go test -coverprofile=coverage.out -covermode=atomic ./...

- name: Upload to Codecov
  uses: codecov/codecov-action@v4
  with:
    files: coverage.out
    flags: unittests
    fail_ci_if_error: true

In Codecov settings, enable branch coverage reports.

---

Achieving 80% Branch Coverage

Strategy 1: Test All Conditional Outcomes

For every if statement, ensure both true and false branches are tested:

func Validate(s string) error {
    if s == "" {
        return errors.New("empty")
    }
    if len(s) > 100 {
        return errors.New("too long")
    }
    return nil
}

func TestValidate(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        wantErr bool
    }{
        {"empty string", "", true},           // if s == "" → true
        {"valid string", "hello", false},     // if s == "" → false
        {"too long", strings.Repeat("x", 101), true},  // if len > 100 → true
        {"at limit", strings.Repeat("x", 100), false}, // if len > 100 → false
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := Validate(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("Validate(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
            }
        })
    }
}

Strategy 2: Cover Compound Conditions

For && and || conditions, test each combination:

func IsEligible(age int, hasLicense bool) bool {
    if age >= 18 && hasLicense {
        return true
    }
    return false
}

func TestIsEligible(t *testing.T) {
    tests := []struct {
        age     int
        license bool
        want    bool
    }{
        {20, true, true},    // Both true
        {20, false, false},  // First true, second false
        {16, true, false},   // First false, second true
        {16, false, false},  // Both false
    }
    // Run all test cases...
}

Strategy 3: Cover Switch Cases

Test all switch cases including default:

func Categorize(score int) string {
    switch {
    case score >= 90:
        return "A"
    case score >= 80:
        return "B"
    case score >= 70:
        return "C"
    default:
        return "F"
    }
}

func TestCategorize(t *testing.T) {
    tests := []struct {
        score int
        want  string
    }{
        {95, "A"},  // First case
        {85, "B"},  // Second case
        {75, "C"},  // Third case
        {65, "F"},  // Default case
    }
    // Run all test cases...
}

Strategy 4: Test Error Paths

Error handling often has low coverage:

func ReadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("read file: %w", err)  // Often untested
    }

    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("parse config: %w", err)  // Often untested
    }

    return &cfg, nil
}

func TestReadConfig(t *testing.T) {
    // Happy path
    t.Run("valid config", func(t *testing.T) {
        cfg, err := ReadConfig("testdata/valid.json")
        require.NoError(t, err)
        require.NotNil(t, cfg)
    })

    // Error path: file not found
    t.Run("file not found", func(t *testing.T) {
        _, err := ReadConfig("nonexistent.json")
        require.Error(t, err)
        require.Contains(t, err.Error(), "read file")
    })

    // Error path: invalid JSON
    t.Run("invalid json", func(t *testing.T) {
        _, err := ReadConfig("testdata/invalid.json")
        require.Error(t, err)
        require.Contains(t, err.Error(), "parse config")
    })
}

---

CI/CD Enforcement

Check and Fail on Low Coverage

# .github/workflows/coverage.yml
- name: Check branch coverage
  run: |
    go test -coverprofile=coverage.out -covermode=atomic ./...

    # Statement coverage as proxy (actual branch coverage requires external tools)
    COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | tr -d '%')

    # For branch coverage, multiply by 0.85-0.9 factor
    # (branch coverage is typically 85-90% of statement coverage)
    ESTIMATED_BRANCH=$(awk -v c="$COVERAGE" 'BEGIN { printf "%.1f", c * 0.85 }')

    echo "Statement coverage: $COVERAGE%"
    echo "Estimated branch coverage: $ESTIMATED_BRANCH%"

    if awk -v b="$ESTIMATED_BRANCH" 'BEGIN { exit !(b >= 80) }'; then
      echo "✓ Branch coverage meets 80% threshold"
    else
      echo "✗ Branch coverage below 80% threshold"
      exit 1
    fi

Using Codecov with Branch Coverage

# codecov.yml
coverage:
  precision: 2
  round: down
  range: "70...100"
  status:
    project:
      default:
        target: 80%
        threshold: 1%
        branches:
          - main
    patch:
      default:
        target: 80%
        threshold: 1%

# Comment settings
comment:
  layout: "reach, diff, flags, files"
  behavior: default
  require_changes: true
  require_base: true
  require_head: true
  branches:
    - main

---

Common Pitfalls

1. Testing Only Happy Paths

// Bad: Only tests success
func TestProcess_Success(t *testing.T) {
    result, _ := Process(validInput)
    assert.Equal(t, expected, result)
}

// Good: Tests all outcomes
func TestProcess(t *testing.T) {
    t.Run("success", func(t *testing.T) { ... })
    t.Run("invalid input", func(t *testing.T) { ... })
    t.Run("timeout", func(t *testing.T) { ... })
}

2. Ignoring Default Cases

// Ensure switch default is covered
switch status {
case Active: ...
case Pending: ...
default:
    // This path is often missed
    return fmt.Errorf("unknown status: %s", status)
}

3. Short-Circuit Evaluation

// if a || b: need tests where a=true, and where a=false,b=true, and where both false
// if a && b: need tests where both true, a=false, and a=true,b=false

---

Tools Comparison

---

Badge Criteria Verification

To verify test_branch_coverage80:

1. Generate coverage report

   go test -coverprofile=coverage.out -covermode=atomic ./...

2. Convert to analyzable format

   gocover-cobertura < coverage.out > coverage.xml

3. Check branch coverage

• Upload to Codecov/Coveralls
• Or use local XML analysis tools
• Or estimate from statement coverage (* 0.85)

4. Document in badge application

• Link to coverage reports
• Show coverage percentage
• Explain measurement methodology

---

Resources

• Go Coverage Documentation
• Codecov Branch Coverage
• gocover-cobertura
• Branch vs Statement Coverage

CI Robustness in Docker/Worktree Environments

Patterns and fixes for CI pipelines that run inside Docker containers or git worktree checkouts, where common assumptions about the .git directory structure break.

1. CaptainHook in Docker

CaptainHook's hook-installer plugin fails in Docker containers and git worktrees where .git is a file (pointing to the bare repo) instead of a directory. The failure aborts Composer's post-install-cmd scripts, silently preventing subsequent plugins from running.

Fix

Add CAPTAINHOOK_DISABLE=true to every Docker-based Composer command:

docker run ... -e CAPTAINHOOK_DISABLE=true ... composer install

In runTests.sh or similar CI scripts, pass the variable into the container environment:

docker compose run -e CAPTAINHOOK_DISABLE=true php composer install --no-interaction

Detection

Find Composer commands that are missing the guard:

grep -n "composer" Build/Scripts/runTests.sh | grep -v "CAPTAINHOOK_DISABLE"

Any match indicates a command that will fail when .git is not a directory (Docker, worktrees, CI shallow clones).

2. PHPStan Extension Installer Verification

phpstan/extension-installer registers extensions during Composer's post-install-cmd phase. If an earlier plugin (such as CaptainHook) aborts that phase, extension-installer never runs, and PHPStan operates without the extensions it needs.

Symptom

PHPStan reports false positives or misses errors that extensions should catch (e.g., PHPStan for Doctrine, phpstan-phpunit).

Verification

After composer install, check the generated config:

# Prefer TYPO3-style .Build/vendor if present; otherwise use vendor/ or $VENDOR_DIR
VENDOR_DIR="${VENDOR_DIR:-vendor}"
if [ -d ".Build/vendor" ]; then
  SEARCH_PATH=".Build/vendor/phpstan/extension-installer/src/GeneratedConfig.php"
else
  SEARCH_PATH="$VENDOR_DIR/phpstan/extension-installer/src/GeneratedConfig.php"
fi

grep -F "EXTENSIONS = []" "$SEARCH_PATH"

If the output shows EXTENSIONS = [], the extension-installer plugin did not execute. This is almost always caused by CaptainHook (or another plugin) failing before extension-installer could run.

Fix

Apply the CaptainHook disable fix from Section 1, then re-run composer install. Verify that GeneratedConfig.php now lists the expected extensions.

3. Lint Scope

PHP lint (php -l) test suites must scan only project source directories, not vendor/ or .Build/. Third-party packages may contain intentional syntax error fixtures (e.g., for their own parser tests), which cause false lint failures.

Wrong -- scans vendor too

find . -name '*.php' ! -path './.Build/*' -exec php -l {} \;

This still includes vendor/ at the project root (if present) and misses the intent of excluding build artifacts.

Acceptable -- find . with proper exclusions

find . -name '*.php' \
  ! -path './vendor/*' ! -path './.Build/*' ! -path './var/*' ! -path './node_modules/*' \
  -exec php -l {} \;

Using find . is fine when it explicitly prunes or excludes third-party and build directories.

Best -- scan only source directories

find Classes Configuration Tests -name '*.php' -exec php -l {} \;

Explicitly list the directories that contain project code. This is faster, deterministic, and immune to third-party fixture files.

Detection

grep -n 'find \.' Build/Scripts/runTests.sh | grep -Ei 'php.*-l|lint'

If the find starts from . without -prune or ! -path exclusions for vendor/, .Build/, var/, etc., the lint scope is too broad.

4. Merge Queue Awareness

When branch protection uses GitHub merge queues, several constraints apply that can surprise CI workflows:

Workflow

1. Address all review comments and resolve threads 2. If the PR has auto-merge enabled and needs fixes:

• Disable auto-merge
• Push the fix commits
• Wait for CI
• Re-enable auto-merge

3. Ensure all review threads are resolved before the PR enters the queue

Detection

Check whether a repository uses merge queues:

gh api repos/{owner}/{repo}/rules/branches/main \
  --jq '.[].parameters.merge_queue_enabled // false'

Related References

• references/ci-patterns.md -- CI/CD pipeline design and Git hooks
• references/general.md -- Universal enterprise readiness checks
• references/security-hardening.md -- Security scanning in CI

CI/CD Patterns

Comprehensive CI/CD patterns for enterprise-ready projects. Covers Git hooks, pipeline design, and quality gates.

1. Git Hooks Strategy

Pre-commit vs Pre-push Division

Principle: Fast feedback locally, thorough verification before sharing.

Lefthook Configuration Example

# .lefthook.yml

pre-commit:
  parallel: true
  commands:
    fmt:
      glob: "*.{go,php,ts,js}"
      run: |
        # Language-specific formatters
        gofmt -w {staged_files} 2>/dev/null || true
        prettier --write {staged_files} 2>/dev/null || true

    lint:
      glob: "*.{go,php,ts}"
      run: |
        golangci-lint run --new-from-rev=HEAD~1 || true
        phpstan analyse --no-progress || true
        eslint {staged_files} || true

    build:
      run: |
        go build ./... || make build

    secrets:
      run: gitleaks protect --staged --no-banner

pre-push:
  parallel: true
  commands:
    test:
      run: |
        go test -race ./...
        # Or: phpunit, npm test, etc.

    lint-full:
      run: golangci-lint run --timeout 5m

    security:
      run: |
        govulncheck ./...
        # Or: composer audit, npm audit, etc.

Hook Bypass Policy

• Never bypass hooks in normal workflow
• Use --no-verify only for:
• Emergency hotfixes (document why)
• WIP commits on feature branches (squash before PR)
• CI must run same checks as hooks (no bypass possible)

2. Comprehensive CI Pipeline

Pipeline Structure

┌─────────────────────────────────────────────────────────────┐
│                        CI Pipeline                          │
├─────────────────────────────────────────────────────────────┤
│  Stage 1: Fast Feedback (parallel)                          │
│  ├── lint (golangci-lint, phpstan, eslint)                 │
│  ├── format-check (gofmt, prettier)                        │
│  ├── build                                                  │
│  └── secrets-scan (gitleaks, trufflehog)                   │
├─────────────────────────────────────────────────────────────┤
│  Stage 2: Testing (parallel by OS/version)                  │
│  ├── unit-tests (ubuntu, macos, windows)                   │
│  ├── integration-tests                                      │
│  ├── fuzz-tests (if applicable)                            │
│  └── benchmarks (optional, for tracking)                   │
├─────────────────────────────────────────────────────────────┤
│  Stage 3: Security (parallel)                               │
│  ├── sast (CodeQL, semgrep)                                │
│  ├── dependency-scan (govulncheck, npm audit)              │
│  ├── container-scan (trivy, if applicable)                 │
│  └── license-check                                          │
├─────────────────────────────────────────────────────────────┤
│  Stage 4: Coverage & Quality (depends on tests)             │
│  ├── coverage-report                                        │
│  └── quality-gate (fail if below threshold)                │
├─────────────────────────────────────────────────────────────┤
│  Stage 5: Artifacts (depends on all above)                  │
│  ├── build-artifacts                                        │
│  └── attestations (SLSA provenance)                        │
└─────────────────────────────────────────────────────────────┘

Preventing Duplicate CI Runs

When a workflow triggers on both push: and pull_request:, pushing to a PR branch causes every job to run twice -- once for the push event and once for the pull_request event. This wastes CI minutes and clutters the checks list.

Fix: Restrict push: to protected branches only:

on:
  push:
    branches: [main]      # Only run on pushes to main (merge commits)
  pull_request:            # Runs on PR open/sync — covers feature branches

Anti-pattern (causes duplicate runs):

on:
  push:                    # BAD: triggers on ALL branch pushes including PR branches
  pull_request:

This applies to all workflow files, not just ci.yml. Audit every .github/workflows/*.yml for unscoped push: triggers.

GitHub Actions Example

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  # Stage 1: Fast Feedback
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: golangci/golangci-lint-action@971e284b6050e8a5849b72094c50ab08da042db8 # v6.1.1
        with:
          version: latest

  secrets-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.8
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # Stage 2: Testing (matrix)
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        go-version: ['1.25.x']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
        with:
          go-version: ${{ matrix.go-version }}
      - run: go test -race -coverprofile=coverage.txt ./...
      - uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d # v5.4.2
        if: matrix.os == 'ubuntu-latest'

  # Stage 3: Security
  codeql:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: github/codeql-action/init@v3
        with:
          languages: go
      - uses: github/codeql-action/autobuild@v3
      - uses: github/codeql-action/analyze@v3

  vulnerability-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
      - run: go install golang.org/x/vuln/cmd/govulncheck@latest
      - run: govulncheck ./...

  # Stage 4: Quality Gate
  quality-gate:
    needs: [lint, test, codeql, vulnerability-scan]
    runs-on: ubuntu-latest
    steps:
      - run: echo "All checks passed"

3. Quality Gates

Coverage Thresholds

Multi-Suite Coverage (MANDATORY)

Coverage must be collected from ALL test suites, not just unit tests:

# PHP: Collect coverage from each test suite
- name: Unit Tests
  run: php -d pcov.enabled=1 .Build/bin/phpunit -c Build/phpunit/UnitTests.xml --coverage-clover .Build/coverage/unit.xml

- name: Integration Tests
  run: php -d pcov.enabled=1 .Build/bin/phpunit -c Build/phpunit/IntegrationTests.xml --coverage-clover .Build/coverage/integration.xml

- name: E2E Tests
  run: php -d pcov.enabled=1 .Build/bin/phpunit -c Build/phpunit/E2ETests.xml --coverage-clover .Build/coverage/e2e.xml

# Upload ALL coverage files
- uses: codecov/codecov-action@SHA # vX.Y.Z
  with:
    files: .Build/coverage/unit.xml,.Build/coverage/integration.xml,.Build/coverage/e2e.xml

Polyglot Coverage (PHP + JavaScript)

Projects with both PHP and JavaScript MUST collect coverage from both:

# PHP Tests
- name: PHP Tests with Coverage
  run: |
    php -d pcov.enabled=1 .Build/bin/phpunit -c Build/phpunit/UnitTests.xml --coverage-clover .Build/coverage/unit.xml
    php -d pcov.enabled=1 .Build/bin/phpunit -c Build/phpunit/IntegrationTests.xml --coverage-clover .Build/coverage/integration.xml

# JavaScript Tests (vitest/jest)
- uses: actions/setup-node@SHA # vX.Y.Z
  with:
    node-version: '22'

- run: npm install

- name: JavaScript Tests with Coverage
  run: npm run test:coverage  # Must output coverage/lcov.info

# Upload ALL coverage
- uses: codecov/codecov-action@SHA # vX.Y.Z
  with:
    files: .Build/coverage/unit.xml,.Build/coverage/integration.xml,coverage/lcov.info

vitest.config.js MUST include lcov reporter:

coverage: {
    provider: 'v8',
    reporter: ['text', 'json', 'html', 'lcov'],  // lcov REQUIRED
    reportsDirectory: 'coverage',
}

Enforcing Coverage

# In CI workflow
- name: Check coverage threshold
  run: |
    COVERAGE=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | tr -d '%')
    if (( $(echo "$COVERAGE < 80" | bc -l) )); then
      echo "Coverage $COVERAGE% is below 80% threshold"
      exit 1
    fi

# For patch coverage (new code only)
- name: Check patch coverage
  run: |
    diff-cover coverage.xml --compare-branch=origin/main --fail-under=90

Codecov Patch Coverage Configuration

Codecov's patch target checks coverage on new/changed lines only. Set a realistic threshold -- lines that require specific PHP extensions (GD, Imagick) or a full TYPO3 bootstrap may be uncoverable in some CI matrix entries but covered in others.

# codecov.yml
coverage:
  status:
    project:
      default:
        target: 80%
    patch:
      default:
        target: 60%          # Realistic for extension code with environment deps
        threshold: 5%        # Allow 5% drop before failing

Key considerations:

• Lines behind extension_loaded('gd') guards may show as uncovered in matrix

entries without that extension

• TYPO3 integration tests may cover code that unit tests cannot reach
• Set patch.target based on what your CI matrix actually covers, not aspirational goals
• Use Codecov flags to separate unit vs integration coverage for clearer reporting

PR Quality Requirements

# Branch protection rules
branch_protection:
  required_status_checks:
    strict: true
    contexts:
      - lint
      - test (ubuntu-latest)
      - test (macos-latest)
      - test (windows-latest)
      - codeql
      - vulnerability-scan

  required_pull_request_reviews:
    required_approving_review_count: 1
    dismiss_stale_reviews: true

  required_linear_history: true  # Enforce rebase

  required_signatures: true      # Signed commits

4. PHPStan Baseline Management

Generating a Baseline

Capture all existing issues so new code is held to a higher standard:

# Generate baseline from current state
vendor/bin/phpstan analyse --generate-baseline

# When codebase is already clean, allow empty baseline
vendor/bin/phpstan analyse --generate-baseline --allow-empty-baseline

This creates phpstan-baseline.neon (or the configured path) containing all currently-known errors, which PHPStan then ignores on subsequent runs.

Baseline CI Strategy

The baseline should shrink over time, never grow. Track this in CI:

- name: PHPStan analysis
  run: vendor/bin/phpstan analyse --no-progress

- name: Check baseline size
  run: |
    if [ -f phpstan-baseline.neon ]; then
      IGNORED=$(grep -c 'message:' phpstan-baseline.neon || echo 0)
      echo "PHPStan baseline: $IGNORED ignored errors"
      # Optional: fail if baseline grew
      # Compare against a known count stored in a tracking file
    fi

Baseline Best Practices

PHPStan Configuration Example

# phpstan.neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
    paths:
        - Classes
    tmpDir: .Build/phpstan

5. Multi-Platform Testing

OS Matrix Strategy

strategy:
  fail-fast: false  # Don't cancel other jobs on failure
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    include:
      # OS-specific configurations
      - os: ubuntu-latest
        artifact-suffix: linux-amd64
      - os: macos-latest
        artifact-suffix: darwin-amd64
      - os: windows-latest
        artifact-suffix: windows-amd64.exe

Version Matrix Strategy

strategy:
  matrix:
    # Test oldest supported and latest
    version: ['1.21', '1.25']  # Or PHP: ['8.1', '8.4']
    include:
      - version: '1.25'
        latest: true  # Upload coverage only from latest

6. Flaky Test Prevention

CI-Specific Test Configuration

# Increase timeouts in CI
- name: Run tests
  run: go test -race -timeout 10m ./...
  env:
    CI: true
    TEST_TIMEOUT_MULTIPLIER: 3

Retry Strategy for Known Flaky Tests

- name: Run tests with retry
  uses: nick-fields/retry@v3
  with:
    timeout_minutes: 10
    max_attempts: 3
    command: go test -race ./...

Detecting Flaky Tests

# Run tests multiple times to detect flakiness
- name: Flaky test detection
  if: github.event_name == 'schedule'  # Nightly only
  run: |
    for i in {1..10}; do
      go test -race ./... || exit 1
    done

7. Caching Strategy

Go Caching

- uses: actions/setup-go@v5
  with:
    go-version: '1.25'
    cache: true  # Caches go mod and build cache

PHP Caching

- name: Cache Composer
  uses: actions/cache@v4
  with:
    path: vendor
    key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}

Node Caching

- uses: actions/setup-node@v4
  with:
    node-version: '22'
    cache: 'npm'

8. Signed Commits Enforcement

Problem: GitHub Can't Sign Rebase Merges

When repository requires signed commits AND only allows rebase merge:

# This fails because GitHub can't sign rebased commits
gh pr merge 123 --rebase
# Error: Base branch requires signed commits

Solution: Local Merge Workflow

# 1. Fetch and checkout main
git checkout main
git pull origin main

# 2. Fast-forward merge (preserves signatures)
git merge feature-branch --ff-only

# 3. Push to main
git push origin main

Automating with PR Labels

# Workflow triggered by 'ready-to-merge' label
on:
  pull_request:
    types: [labeled]

jobs:
  merge:
    if: github.event.label.name == 'ready-to-merge'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.MERGE_TOKEN }}  # PAT with push access

      - name: Merge PR
        run: |
          git checkout main
          git merge origin/${{ github.head_ref }} --ff-only
          git push origin main

9. Reusable Workflow Pinning

Supply Chain Security for Reusable Workflows

All uses: references to third-party reusable workflows must be pinned to commit SHAs, just like regular actions:

# BAD: branch reference is mutable (supply chain risk)
jobs:
  ci:
    uses: org/shared-workflows/.github/workflows/ci.yml@main

# BAD: tag reference is also mutable
jobs:
  ci:
    uses: org/shared-workflows/.github/workflows/ci.yml@v2

# GOOD: SHA-pinned (immutable reference)
jobs:
  ci:
    uses: org/shared-workflows/.github/workflows/ci.yml@a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 # v2.1.0

Exception: Org-Internal Workflows

Org-internal reusable workflows (maintained by the same organization) should use `@main` or `@tag`, not SHAs. SHA-pinning org-internal workflows is an anti-pattern because it breaks centralized security update propagation.

See checkpoints.yaml ER-33 for the enforcement rule.

Auditing Workflow References

# Find all reusable workflow references
grep -rn 'uses:.*\.github/workflows/.*\.yml@' .github/workflows/

# Find unpinned references (tag or branch, no SHA)
grep -rn 'uses:.*\.github/workflows/.*\.yml@' .github/workflows/ | grep -v '@[a-f0-9]\{40\}'

Related References

• references/ci-docker-worktree.md - Docker/worktree CI robustness (CaptainHook, lint scope, merge queues)
• references/security-hardening.md - Security scanning details
• references/code-review.md - Code quality checklist
• references/signed-releases.md - Release signing
• assets/workflows/ - Ready-to-use workflow templates

Code Review Quality Patterns

Language-agnostic code review checklist and patterns for ensuring production-quality code. These patterns apply to Go, PHP, TypeScript, Python, and other languages.

Code Review Checklist

Before approving any PR, verify these patterns:

1. Test Resource Management

Issue: Tests creating multiple instances of the same resource when only one is needed.

Check:

• [ ] Is there exactly ONE instance of each configurable resource per test?
• [ ] Is the resource fully configured at creation time (not reconfigured later)?
• [ ] Are shared counters/state isolated between test resources?

Bad Example:

func TestFeature(t *testing.T) {
    // BAD: Creates two instances, first is unused
    c := NewClient(WithTimeout(5))
    _, _ = c.AddJob("* * * * *", myJob)

    c = NewClient(WithTimeout(5), WithLogger(logger))  // Replaced!
    _, _ = c.AddJob("* * * * *", myJob)
    c.Start()
}

Good Example:

func TestFeature(t *testing.T) {
    // GOOD: Single instance, fully configured
    c := NewClient(
        WithTimeout(5),
        WithLogger(logger),
    )
    _, _ = c.AddJob("* * * * *", myJob)
    c.Start()
}

2. State Mutation Completeness

Issue: Operations that logically change state but don't update tracking fields.

Check:

• [ ] After operations complete, are ALL related tracking fields updated?
• [ ] On restart/retry, will the state be correct?
• [ ] Are side effects committed atomically with the main operation?

Bad Example:

func (s *Scheduler) handleMissedRuns(entry *Entry, missed []time.Time) {
    for _, t := range missed {
        s.runJob(entry, t)
    }
    // BAD: entry.LastRun not updated - will re-run on restart!
}

Good Example:

func (s *Scheduler) handleMissedRuns(entry *Entry, missed []time.Time) {
    for _, t := range missed {
        s.runJob(entry, t)
    }
    // GOOD: Update tracking state after execution
    entry.LastRun = missed[len(missed)-1]
}

3. Defensive Enum/Const Handling

Issue: Switch statements on enums without handling unknown values.

Check:

• [ ] Does the enum type have a Valid() or IsValid() method?
• [ ] Do switch statements have a default case?
• [ ] Is the default case tested explicitly?
• [ ] Are unexpected values logged for debugging?

Bad Example:

func (p Policy) Apply() {
    switch p {
    case PolicyA:
        doA()
    case PolicyB:
        doB()
    // BAD: No default case - silently ignores invalid values
    }
}

Good Example:

// Valid returns true if the policy is a known valid value
func (p Policy) Valid() bool {
    return p >= PolicyA && p <= PolicyB
}

func (p Policy) Apply() error {
    switch p {
    case PolicyA:
        doA()
    case PolicyB:
        doB()
    default:
        // GOOD: Log and handle unexpected values
        log.Warn("unexpected policy value", "policy", int(p))
        return fmt.Errorf("invalid policy: %d", p)
    }
    return nil
}

Testing Default Case:

func TestPolicyApply_InvalidPolicy(t *testing.T) {
    p := Policy(99)  // Invalid value
    err := p.Apply()
    if err == nil {
        t.Error("expected error for invalid policy")
    }
}

4. Documentation Accuracy

Issue: Documentation claims that don't match actual behavior or benchmarks.

Check:

• [ ] Are performance claims verified against actual benchmark output?
• [ ] Are negative trade-offs documented (memory increase, complexity)?
• [ ] Do code examples include all necessary imports?
• [ ] Do code examples handle errors appropriately?

Bad Example:

## Performance
WithCapacity provides ~6% improvement in bulk operations.

(When benchmarks actually show 12% improvement)

Good Example:

## Performance
WithCapacity provides ~12% improvement in bulk addition time (based on
BenchmarkBulkAdd: 128342 ns/op without vs 113338 ns/op with capacity).

Trade-off: ~3% higher memory usage due to pre-allocated capacity.

5. Platform-Specific Code

Issue: Code that only works on certain platforms without documentation.

Check:

• [ ] Is platform-specific code clearly marked?
• [ ] Are limitations documented in comments?
• [ ] Are alternatives provided for unsupported platforms?
• [ ] Are build tags used where appropriate?

Bad Example:

func lockFile(f *os.File) error {
    return syscall.Flock(int(f.Fd()), syscall.LOCK_EX)
}

Good Example:

// lockFile acquires an exclusive lock on the file.
// NOTE: This uses flock() which is Unix-specific (Linux, macOS, BSD).
// On Windows, use LockFileEx from golang.org/x/sys/windows.
//
//go:build !windows
func lockFile(f *os.File) error {
    return syscall.Flock(int(f.Fd()), syscall.LOCK_EX)
}

6. Defensive Code Coverage

Issue: Defensive code paths (error handling, edge cases) not tested.

Check:

• [ ] Are default switch cases covered by tests?
• [ ] Are error paths tested (not just happy path)?
• [ ] Are boundary conditions tested?
• [ ] Is validation logic tested with invalid inputs?

Strategy for Testing Defensive Code:

// To test defensive code that's normally unreachable,
// bypass normal validation and call internal functions directly

func TestHandleInvalidState(t *testing.T) {
    // Create object in invalid state (bypassing constructor validation)
    obj := &MyObject{
        state: InvalidState(99),
    }

    // Call method that has defensive handling
    err := obj.Process()

    // Verify defensive code executed correctly
    if err == nil {
        t.Error("expected error for invalid state")
    }
}

Review Process Quality

Required Conversation Resolution (Branch Protection)

Enable required_conversation_resolution in branch protection to enforce that all review threads are resolved before merging. Without this, review feedback can be silently ignored — especially problematic when automated reviewers (e.g., GitHub Copilot) leave actionable comments.

# Check if enabled
gh api repos/{owner}/{repo}/branches/main/protection \
  --jq 'if .required_conversation_resolution.enabled then "✅ Enabled" else "❌ NOT enabled" end'

See references/github.md → "Review Enforcement" for full setup instructions.

PR Review Thread Resolution

When addressing review feedback:

1. Fix the code - Address the feedback 2. Reply to the thread - Explain what was changed (use GraphQL API to reply to thread, not new comment) 3. Resolve the thread - Mark as resolved after fix is pushed 4. Verify CI - Ensure all checks still pass

Review Comment Quality

Good review comments:

• Explain WHY something is problematic
• Provide a concrete suggestion or example
• Reference documentation or standards when applicable

Language-Specific Implementations

Integration with CI

Add these checks to your CI pipeline:

# Example: Ensure test coverage for new code
- name: Check patch coverage
  run: |
    # Fail if new code has < 90% coverage
    diff-cover coverage.xml --fail-under=90

Related References

• references/documentation.md - Documentation standards
• references/ci-patterns.md - CI/CD automation
• references/security-hardening.md - Security patterns

Dependency CVE Workflow

When assessing enterprise readiness, always run dependency audit as part of discovery.

Audit Commands

# PHP/Composer
composer audit

# Node.js
npm audit

# Python
pip-audit

# Go
govulncheck ./...

CVE Handling Best Practice

Separate dependency updates from code changes:

Real-world example from t3x-cowriter review:

• Found 4 CVEs during enterprise assessment
• CVE fixes required composer update typo3/cms-core typo3/cms-backend
• Kept separate from code fixes (JS bug, AGENTS.md updates) for clean PR history

CVE Severity Response

CI Integration

Add dependency audit to CI pipeline:

# .github/workflows/ci.yml
- name: Security audit
  run: composer audit --format=plain

Developer Certificate of Origin (DCO) Implementation Guide

The DCO is a lightweight way to certify that contributors have the right to submit their code under the project's license.

What is DCO?

The Developer Certificate of Origin is a legal statement that contributors make when submitting code:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution is maintained
    indefinitely and may be redistributed consistent with this project
    or the open source license(s) involved.

Implementation Steps

1. Document DCO in CONTRIBUTING.md

Add this section to your CONTRIBUTING.md:

## Developer Certificate of Origin (DCO)

All contributions to this project must be signed off using the DCO.

### Sign Your Commits

Use the `-s` flag when committing:

\`\`\`bash
git commit -s -m "feat: add new feature"
\`\`\`

This adds a `Signed-off-by` line to your commit message:

\`\`\`
feat: add new feature

Signed-off-by: Your Name <your.email@example.com>
\`\`\`

### Retroactive Sign-off

If you forgot to sign a commit:

\`\`\`bash
# For the last commit
git commit --amend -s

# For multiple commits
git rebase --signoff HEAD~N
\`\`\`

### Configure Git for Automatic Sign-off

\`\`\`bash
git config --global alias.cs "commit -s"
\`\`\`

2. Add GitHub Action for Enforcement

Create .github/workflows/dco.yml:

name: DCO Check

on:
  pull_request:
    branches: [main, master]

permissions:
  contents: read
  pull-requests: read

jobs:
  dco:
    name: DCO Check
    runs-on: ubuntu-latest
    steps:
      - name: Check DCO
        uses: dcoapp/app@v1

3. Add DCO to PR Template

Add to .github/PULL_REQUEST_TEMPLATE.md:

## DCO Sign-off

- [ ] I have signed off all commits in this PR (`git commit -s`)

By submitting this PR, I certify that my contribution is made under
the terms of the Developer Certificate of Origin.

Verification

Check a Commit

git log --format='%h %s%n  Signed-off-by: %aN <%aE>' -1

Verify All Commits in a PR

git log origin/main..HEAD --format='%h %B' | grep -B1 "Signed-off-by:"

Common Issues

1. Missing Sign-off

Error: "DCO check failed"

Fix:

git rebase --signoff HEAD~N
git push --force-with-lease

2. Email Mismatch

Error: "Email in sign-off doesn't match commit author"

Fix:

git config user.email "your.email@example.com"
git commit --amend -s

3. Corporate Email Required

Some projects require corporate email addresses. Configure:

git config user.email "you@company.com"

DCO vs CLA

OpenSSF Badge Requirements

For Silver level:

• dco: The project MUST have a way to ensure contributors have rights to contribute

This is satisfied by: 1. DCO enforcement (recommended) 2. CLA (Contributor License Agreement) 3. Clear license in CONTRIBUTING.md

References

• Developer Certificate of Origin
• DCO GitHub App
• Git sign-off documentation