Enterprise Readiness Assessment

When to Use

• Evaluating projects for production/enterprise readiness
• Implementing supply chain security (SLSA, signing, SBOMs)
• Hardening CI/CD pipelines
• Establishing quality gates
• Pursuing OpenSSF Best Practices Badge (Passing/Silver/Gold)
• Reviewing code or PRs for quality
• Writing ADRs, changelogs, or migration guides
• Configuring Git hooks or CI pipelines

MANDATORY Requirements

CRITICAL: The following are NOT optional. Every project MUST have ALL of these. Do not skip any.

README Badges (MANDATORY)

Every project README.md MUST display these badges at the top, in this order:

<!-- Row 1: CI/Quality -->
[![CI](https://github.com/ORG/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/ORG/REPO/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/ORG/REPO/graph/badge.svg)](https://codecov.io/gh/ORG/REPO)

<!-- Row 2: Security (MANDATORY) -->
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ORG/REPO/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ORG/REPO)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/PROJECT_ID/badge)](https://www.bestpractices.dev/projects/PROJECT_ID)

github.com/ORG/REPO/actions/workflows/ci.yml/badge.svg

codecov.io/gh/ORG/REPO/graph/badge.svg

api.securityscorecards.dev/projects/github.com/ORG/REPO/badge

www.bestpractices.dev/projects/PROJECT_ID/badge

CI/CD Workflows (MANDATORY)

Every GitHub project MUST have these workflows in

.github/workflows/

ci.yml

codeql.yml

scorecard.yml

dependency-review.yml

CI Must Include (MANDATORY)

codecov/codecov-action

composer audit

npm audit

govulncheck

OpenSSF Registration (MANDATORY)

1. Register at bestpractices.dev: https://www.bestpractices.dev/en/projects/new
2. Note the Project ID assigned after registration
3. Add badge to README with correct PROJECT_ID
4. Run Scorecard workflow to generate initial score

Codecov Setup (MANDATORY)

1. Enable Codecov for the repository at codecov.io
2. Collect coverage from ALL test suites (not just unit tests):

phpunit -c UnitTests.xml --coverage-clover

.Build/coverage/unit.xml

phpunit -c IntegrationTests.xml --coverage-clover

.Build/coverage/integration.xml

phpunit -c E2ETests.xml --coverage-clover

.Build/coverage/e2e.xml

phpunit -c FunctionalTests.xml --coverage-clover

.Build/coverage/functional.xml

npm run test:coverage

coverage/lcov.info

3. Upload ALL coverage files to Codecov:

   - uses: codecov/codecov-action@SHA # vX.Y.Z
     with:
       token: ${{ secrets.CODECOV_TOKEN }}  # MANDATORY - see below
       files: .Build/coverage/unit.xml,.Build/coverage/integration.xml,.Build/coverage/e2e.xml,coverage/lcov.info
       fail_ci_if_error: false
   

CODECOV_TOKEN (MANDATORY)

Never rely on tokenless uploads. They fail for protected branches and are unreliable.

CODECOV_TOKEN

token: ${{ secrets.CODECOV_TOKEN }}

Failure without token:

Upload failed: {"message":"Token required because branch is protected"}

Get token from: https://app.codecov.io/gh/ORG/REPO/settings

Add as org secret (recommended):

# Organization-level (covers all repos)
gh secret set CODECOV_TOKEN --org netresearch --visibility all

# Or repository-level
gh secret set CODECOV_TOKEN --repo OWNER/REPO

JavaScript Coverage (MANDATORY for projects with JS/TS)

When a project contains JavaScript or TypeScript files:

1. vitest.config.js MUST include lcov reporter for Codecov:

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

2. CI workflow MUST include JavaScript test job:

   - uses: actions/setup-node@SHA # vX.Y.Z
     with:
       node-version: '22'
   - run: npm install
   - run: npm run test:coverage
   

3. Codecov upload MUST include

   coverage/lcov.info

Verification Checklist

Before marking enterprise-readiness complete, verify ALL:

• README has CI badge linking to workflow
• README has Codecov badge (not "unknown")
• README has OpenSSF Scorecard badge (correct URL with

  api.securityscorecards.dev

  )
• README has OpenSSF Best Practices badge (correct PROJECT_ID, not placeholder)

• .github/workflows/ci.yml

  exists and uploads coverage

• .github/workflows/codeql.yml

  exists

• .github/workflows/scorecard.yml

  exists
• Codecov shows actual coverage percentage
• Scorecard shows actual score

If any badge shows "unknown", "invalid", or placeholder ID - FIX IT. Do not proceed.

Assessment Workflow

1. Discovery: Identify platform (GitHub/GitLab), languages, existing CI/CD
2. Scoring: Apply checklists from references based on stack
3. Badge Assessment: Check OpenSSF criteria status
4. Gap Analysis: List missing controls by severity
5. Implementation: Apply fixes using scripts and templates

Dependency CVE Workflow

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

# PHP/Composer
composer audit

# Node.js
npm audit

# Python
pip-audit

# Go
govulncheck ./...

CVE Handling Best Practice

Separate dependency updates from code changes:

composer update

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

Reference Files (Load Based on Stack)

references/general.md

references/github.md

references/go.md

references/openssf-badge-silver.md

references/openssf-badge-gold.md

Quality & Process References (Language-Agnostic)

references/code-review.md

references/documentation.md

references/ci-patterns.md

Explicit Content Triggers

When reviewing PRs or code, load

references/code-review.md

When writing ADRs (Architecture Decision Records), load

references/documentation.md

When writing changelogs or release notes, load

references/documentation.md

When writing API documentation or migration guides, load

references/documentation.md

When configuring CI/CD pipelines, load

references/ci-patterns.md

When setting up Git hooks (pre-commit/pre-push), load

references/ci-patterns.md

When enforcing coverage thresholds, load

references/ci-patterns.md

When handling signed commits with rebase-only merge, load

references/ci-patterns.md

Implementation Guides

references/quick-start-guide.md

references/dco-implementation.md

references/signed-releases.md

references/reproducible-builds.md

references/security-hardening.md

references/solo-maintainer-guide.md

references/branch-coverage.md

Automation Scripts

scripts/verify-badge-criteria.sh

scripts/check-coverage-threshold.sh

scripts/check-branch-coverage.sh

scripts/add-spdx-headers.sh

scripts/verify-signed-tags.sh

scripts/verify-review-requirements.sh

Document Templates

Templates in

assets/templates/

• GOVERNANCE.md

  - Project governance (Silver)

• ARCHITECTURE.md

  - Technical docs (Silver)

• CODE_OF_CONDUCT.md

  - Contributor Covenant v3.0

• SECURITY_AUDIT.md

  - Security audit (Gold)

• BADGE_EXCEPTIONS.md

  - N/A justifications

CI Workflow Templates

GitHub Actions workflows in

assets/workflows/

scorecard.yml

codeql.yml

dependency-review.yml

slsa-provenance.yml

dco-check.yml

Copy workflows to

.github/workflows/

Scoring Interpretation

Code Review Quick Checklist

Before approving PRs, verify (see

references/code-review.md

• One resource per test - No duplicate instances
• State mutation complete - Tracking fields updated after operations
• Defensive enum handling -

  Valid()

  method,

  default

  case, tested
• Documentation accurate - Claims match benchmarks, trade-offs noted
• Platform code marked - Limitations documented, alternatives provided
• Defensive code tested - Error paths and edge cases covered

Critical Rules

• NEVER interpolate

  ${{ github.event.* }}

  in

  run:

  blocks (script injection)
• NEVER guess action versions - always fetch from GitHub API
• ALWAYS use SHA pins for actions with version comments
• ALWAYS verify commit hashes against official tags

Related Skills

go-development

github-project

security-audit

git-workflow

Resources

• OpenSSF Scorecard
• Best Practices Badge
• SLSA Framework
• S2C2F

Contributing: Improvements to this skill should be submitted to the source repository: https://github.com/netresearch/enterprise-readiness-skill