Skip to content

SKILL.md

Latest commit

 

History

History
99 lines (72 loc) · 8.13 KB

SKILL.md

File metadata and controls

99 lines (72 loc) · 8.13 KB
Raw
name github-repo-setup
description Assess GitHub repository maturity against BC Gov DevOps and security standards. Generates a MATURITY_REPORT.md scorecard covering branch protection rulesets, TypeScript strictness, Renovate preset tracing, vulnerability SLAs, CI/CD quality gates, and OpenShift container security. Use when onboarding repos, running compliance reviews, or evaluating vendor conformance.
owner bcgov
tags
github-repo-setup
devops
security
bcgov
audit
compliance

GitHub Repository Setup Validation

Evaluate repository compliance against BC Gov DevOps and security standards by inspecting config files, querying GitHub APIs, and generating a structured maturity report.

Use When

  • Onboarding a new repository to a BC Gov GitHub organization.
  • Preparing for a security audit, compliance review, or sprint planning.
  • Evaluating a repository before transitioning it to maintenance mode.
  • Validating vendor compliance with BC Gov digital standards.

Don't Use When

  • Auditing personal, experimental, or toy repositories, or repository templates/scaffolding not containing production content. (BC Gov documentation-only or basic scripting repositories ARE in scope; assess them with inapplicable dimensions marked N/A).
  • Performing actual resource provisioning, template setup, or automated repository scaffolding (this skill is purely an assessment and compliance validation auditor).

Workflow

  1. Analyze Project Structure — Walk the repo root and identify: package.json, tsconfig.json, renovate.json or dependabot.yml, .github/workflows/, OpenShift/Kubernetes manifests, SECURITY.md, .github/ISSUE_TEMPLATE/.

  2. Inspect Server-side Config (Dimensions 1–2) — Use gh api graphql to query repository settings and branch rulesets. If gh CLI is unavailable, mark findings as Unverified (distinct from Not Met). See REFERENCE.md query example.

  3. Inspect Code and File-based Config (Dimensions 3–5, 8–9):

    • Read tsconfig.json for strict: true; grep for @ts-ignore, @ts-nocheck, eslint-disable.
    • Read renovate.json — trace preset inheritance through extends entries to determine effective automerge, schedule, and minimumReleaseAge settings.
    • Read .github/workflows/ for test/coverage/scan gates.
    • Read deployment manifests for runAsNonRoot, readOnlyRootFilesystem, probes.

  4. Assess Processes and Docs (Dimensions 6–7) — Read SECURITY.md and issue templates for documented triage workflow and SLAs. Read workflows for image promotion patterns.

  5. Draft and Write Report — Score each of the 9 dimensions using the formula: Compliance Score (%) = (Sum of Weighted Dimension Scores / Total Scored Dimensions) × 100 (where Met = 1.0, Partial = 0.5, Not Met = 0.0, and Unverified/N/A are excluded from both numerator and denominator). Calculate compliance percentage, map to Maturity Level 1–5, and generate MATURITY_REPORT.md in the audited repo root using the report template.

Rules

All dimension definitions and scoring details are in REFERENCE.md.

Nine Compliance Dimensions

  • Dim 1 – Repo Settings: Squash merging enforced, auto-cleanup, suggest updates. Requires GitHub API.
  • Dim 2 – Branch Rulesets: PR requirement, approvals, linear history, status checks. Requires gh api graphql.
  • Dim 3 – Code Hygiene: TS strict mode, linting enforced, no diagnostic escapes, 80%+ test coverage.
  • Dim 4 – Secrets: Token/password separation per environment, 32+ char passwords.
  • Dim 5 – Dependency Updates: Renovate/Dependabot configured, BC Gov preset preferred, 7-day minimum release age, automerge enabled. Trace preset inheritance.
  • Dim 6 – Vulnerability SLAs: Documented triage workflow, CISA KEV monitoring, FIRST EPSS scoring. Critical 24h / High 1w / Medium 2w / Low next scheduled release.
  • Dim 7 – CI/CD and Deployments: PR preview envs, image promotion (no rebuilds), SHA-based image references, deployment health gating.
  • Dim 8 – Quality Gates: TS/lint/test/coverage/scan failures block merge.
  • Dim 9 – OpenShift Security: Pod security contexts (runAsNonRoot, readOnlyFS), capabilities dropped, seccomp, probes. For remediation, defer to openshift-deployment SKILL.

Critical Rules

  • No-Exemption Policy: All security vulnerabilities must be remediated. No exceptions for "trusted environments" or "internal access."
  • Unverified vs Not Met: When a data source (GitHub API, gh CLI) is unavailable, mark as Unverified — not "Not Met." Do not fabricate findings.
  • Renovate Preset Tracing: Trace all extends entries, fetch referenced preset repos, merge with local overrides, report effective settings.
  • Cross-Reference: For OpenShift manifest remediation, defer to openshift-deployment SKILL.

Output Format

Generate MATURITY_REPORT.md in the audited repo root using the report template in REFERENCE.md.

Report includes: Executive Summary (score, level, date), 9-dimension breakdown table, detailed checklist with legend markers ([x] Met, [~] Partial, [ ] Not Met, [?] Unverified, [-] N/A), scoring formula, and prioritized remediation (Tier 1 blocking, Tier 2 recommended, Tier 3 optional).

Examples

Example 1: Production Microservice

Prompt: "Assess bcgov/my-api-service for compliance" Process: Walk repo → find TypeScript + Renovate + OpenShift manifests → verify strict: true → trace Renovate preset inheritance → check pod security contexts → score 85% (gaps: missing PDB, coverage at 78%) → generate report. Output: MATURITY_REPORT.md with Level 4 (Managed), 2 Tier-2 remediation items.

Example 2: New Repository Onboarding

Prompt: "Is this repo ready for BC Gov production?" Process: Walk repo → find React app, no renovate.json, no branch ruleset → score 55% → flag Tier-1 blockers. Output: MATURITY_REPORT.md with Level 3 (Defined), 4 Tier-1 blocking items.

Edge Cases

  • Monorepos: Inspect root tsconfig.json and workspace-level configs. Flag inconsistencies across packages.
  • Non-TypeScript Repos: Skip TS-specific rules. Assess language-appropriate linting (ESLint for JS, Pylint for Python).
  • GitHub API Unavailable: Mark Dims 1–2 as Unverified. Example: "Unverified (GitHub API access required). Recommend: gh auth login and re-run."
  • Renovate Config Without Extends: Note default Renovate behavior applies. Verify manual config is comprehensive.
  • Legacy Branch Names (master, develop): Audit still applies. Flag as low-priority gap.
  • Exempt Repos: Documentation-only or archived repos — mark dimensions N/A with documented reason.
  • Reproducibility: Two runs on the same repo must produce identical scores. Use explicit rubric; mark Unverified rather than guessing.
  • Stable Tags vs. Cryptographic Digests: Using unique stable tags (e.g. Git commit SHAs, PR numbers) solves basic config drift but lacks registry-level immutability. Score the SHA-based image references check as Partial (not Met). Only true container image digests (@sha256:...) qualify for Met.

References