cncf-migration-health-monitor

name	cncf-migration-health-monitor
description	Integrate CNCF CLOMonitor and OpenSSF Scorecard into CI/CD to continuously validate open-source project health after a GHES-to-github.com migration. Specific to CNCF OSS migration post-validation workflows.

When to Use This Skill

Use this skill when:

• A repository has just been published to github.com and needs health baseline scoring
• Adding automated OSS health checks to CI/CD pipelines
• Monitoring contributor velocity, compliance docs, and security posture over time

Do NOT use for internal-only repositories or pre-migration validation (use cncf-migration-secrets-scrubber for that).

Tools and Services

Tool	What it checks	Integration
CLOMonitor	Docs, license, security policy, OpenSSF badge, DCO, changelog	REST API + weekly scan
OpenSSF Scorecard	Supply chain, branch protection, dependencies, signed commits	GitHub Actions
OpenSSF Best Practices Badge	Manual self-assessment against FLOSS criteria	Web form

Step 1 — Enable OpenSSF Scorecard in CI

Add this workflow to .github/workflows/ (runs on push to main and weekly):

name: OpenSSF Scorecard
on:
  push:
    branches: [main]
  schedule:
    - cron: '30 1 * * 1'   # every Monday at 01:30 UTC

permissions:
  security-events: write
  id-token: write
  contents: read
  actions: read

jobs:
  scorecard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: ossf/scorecard-action@v2.4.0
        with:
          results_file: scorecard-results.sarif
          results_format: sarif
          publish_results: true

      - uses: actions/upload-artifact@v4
        with:
          name: scorecard-results
          path: scorecard-results.sarif

      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: scorecard-results.sarif
          category: supply-chain

Key checks Scorecard runs:

• Branch-Protection — requires PR reviews, dismisses stale reviews
• Token-Permissions — workflow tokens scoped to minimum required
• Pinned-Dependencies — all uses: at full commit SHA (not floating tags)
• Signed-Releases — release artifacts are signed
• Dependency-Update-Tool — Dependabot or Renovate configured
• SAST — static analysis runs in CI (CodeQL, semgrep, etc.)

Step 2 — Add OpenSSF Badge to README

# Trigger initial Scorecard run by pushing to main, then badge URL becomes available
# Format:
# https://api.securityscorecards.dev/projects/github.com/<ORG>/<REPO>/badge

Add to README.md:

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

Step 3 — Register with CLOMonitor

CLOMonitor is the CNCF's official project health dashboard at https://clomonitor.io.

It scans registered projects weekly against these categories:

Check	What it looks for
Documentation	README, CONTRIBUTING, CODE_OF_CONDUCT, CHANGELOG, governance
License	SPDX-compatible license at root
Best practices	OpenSSF badge, CLA/DCO, community meeting notes
Security	SECURITY.md, signed releases, private vulnerability reporting
Legal	License scanning, trademark policy

To register a project (requires CNCF TOC or project sponsorship):

1. Open a PR to https://github.com/cncf/clomonitor adding your project to data/projects/<foundation>/<project>.yml
2. CLOMonitor will begin weekly scanning automatically

For non-CNCF orgs, run the CLOMonitor linter locally:

# Clone and build the linter (Rust)
git clone https://github.com/cncf/clomonitor
cd clomonitor
cargo build --release -p clomonitor-linter

# Lint your project
./target/release/clomonitor-linter \
  --path /path/to/your/repo \
  --url https://github.com/<ORG>/<REPO>

Step 4 — Automate CLOMonitor Linter in CI

name: CLOMonitor Lint
on:
  push:
    branches: [main]
  pull_request:
    paths:
      - 'README.md'
      - 'SECURITY.md'
      - 'CONTRIBUTING.md'
      - 'LICENSE'
      - 'CHANGELOG.md'
      - '.github/**'

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

      - name: Install CLOMonitor linter
        run: |
          curl -sSfL \
            https://github.com/cncf/clomonitor/releases/latest/download/clomonitor-linter-linux-amd64 \
            -o /usr/local/bin/clomonitor-linter
          chmod +x /usr/local/bin/clomonitor-linter

      - name: Run CLOMonitor linter
        run: |
          clomonitor-linter \
            --path . \
            --url https://github.com/${{ github.repository }} \
            --check-set code-review \
            --check-set documentation \
            --check-set license \
            --check-set best-practices \
            --check-set security

Step 5 — Track Contributor Velocity

CLOMonitor measures commit and contributor activity. To ensure good scores:

1. Use .mailmap — canonical author identities dedup contributor counts
2. Use DCO sign-off — Signed-off-by lines count as verified contributions
3. Tag releases — annotated tags are tracked by CLOMonitor for release cadence
4. Community meetings — link meeting notes in README (improves governance score)

Health Score Targets (CNCF Sandbox baseline)

Category	Target score
Documentation	≥ 75%
License	100%
Best Practices	≥ 60%
Security	≥ 70%
OpenSSF Scorecard	≥ 5.0 / 10

Current Vionix Status

# Check after pushing to github.com:
curl -s "https://api.securityscorecards.dev/projects/github.com/Viasat/vionix" \
  | python3 -c "import json,sys; r=json.load(sys.stdin); print('Score:', r.get('score'))"

Related Skills

• cncf-migration-compliance-docs — ensure required docs are present before registering
• cncf-migration-ghes-to-github — push the clean history before running these checks