Run a no-token CI/CD preflight before your next release

Most release checklists focus on the code that ships. But a lot of release pain comes from the repository around the code:

• a GitHub Actions workflow still using an old action major,
• test reports disappearing when CI fails,
• a release job with broad write permissions,
• missing SECURITY.md or CODEOWNERS,
• no dependency update config,
• publish workflows that are hard to audit before a tag is pushed.

These are usually small fixes, but they are easiest to catch before a repo is public, before a package release, or before a CI change becomes urgent.

That is the use case for Repository Hygiene / CI Risk Preflight: a no-token GitHub Action and local CLI for repository hygiene and CI/CD release-readiness signals.

It reads files from a checked-out repository and produces a report. It does not call the GitHub API, require a token, upload source code, or need a SaaS account.

What it checks

The scanner is intentionally conservative. It looks for practical signals that maintainers often review by hand:

• CI deprecations: old GitHub Actions majors such as actions/upload-artifact@v3, actions/download-artifact@v3, actions/cache@v3, actions/checkout@v3, and actions/setup-node@v3.
• CI runtime risk: local JavaScript actions using obsolete Node runtimes.
• Workflow permissions: broad write-all, contents: write, and pull_request_target review prompts.
• Repo hygiene: missing CODEOWNERS, SECURITY.md, CONTRIBUTING.md, changelog/release history.
• Dependency hygiene: missing Dependabot/Renovate config.
• CI observability: missing report artifacts or uploads that do not run with if: always().
• Release safety: publish/release workflows without visible guardrails.
• CI cost/safety: jobs without visible timeout-minutes.

It is not a compliance scanner and it is not a replacement for security review. The goal is a fast preflight report you can run before a release or use as a report-only CI job.

Use it from GitHub Actions

name: repo-hygiene-preflight
on:
  pull_request:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  hygiene:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vasiliy0/repo-hygiene-ci-risk-preflight@v0.1.1
        with:
          format: markdown
          output: repo-hygiene-report.md

For gradual rollout, keep it report-only at first. After the team agrees on the baseline, turn on a gate only for findings that should block a merge or release.

Marketplace listing: https://github.com/marketplace/actions/repository-hygiene-ci-risk-preflight

Or run it locally

python3 -m pip install repo-hygiene-ci-risk-preflight
repo-hygiene-preflight . --format markdown

Generate JSON for automation:

repo-hygiene-preflight . --format json --output repo-hygiene-report.json

Use a severity gate after reviewing the first report:

repo-hygiene-preflight . --fail-on-severity high

Example findings

A report may include findings like:

- high workflow-write-all-permissions
  Why: Broad workflow permissions increase blast radius if a workflow is abused.
  Fix: Prefer least-privilege permissions at workflow/job scope.

- medium missing-security-policy
  Why: Public repos should tell users how to report vulnerabilities.
  Fix: Add SECURITY.md with supported versions and a private reporting path.

- medium missing-ci-report-artifact
  Why: Test-heavy CI is harder to debug when reports disappear after failed runs.
  Fix: Upload test reports/logs with actions/upload-artifact@v4 or write a concise step summary.

Baselines for existing repos

Existing repositories often have known issues that should not block every PR immediately. The scanner supports config and baselines so you can adopt it incrementally:

repo-hygiene-preflight . --format json --output report.json --write-baseline repo-hygiene-baseline.json
repo-hygiene-preflight . --baseline repo-hygiene-baseline.json --fail-on-severity high

Example config:

{
  "ignore_rules": ["workflow-without-timeout"],
  "ignore_paths": ["docs/generated/**"],
  "severity_overrides": {"missing-contributing": "info"},
  "baseline_fingerprints": []
}

When this is useful

This kind of preflight is useful before:

• publishing a new open-source repo,
• cutting a package release,
• adding CI as a required branch check,
• migrating old GitHub Actions workflows,
• preparing a repository for external contributors,
• reviewing release workflows that publish packages, containers, docs, or artifacts.

The best first run is usually report-only. If the report finds nothing, great. If it finds issues, most are small checklist items that are easier to fix before they become release blockers.

Links

• GitHub Marketplace Action: https://github.com/marketplace/actions/repository-hygiene-ci-risk-preflight
• GitHub repo: https://github.com/vasiliy0/repo-hygiene-ci-risk-preflight
• PyPI: https://pypi.org/project/repo-hygiene-ci-risk-preflight/