feat: align to reference standards (.reference.yaml, CoC, AGENTS+.ai, CONTRIBUTING re-issue, posture link)

Andrew Dunnrequested to merge
andunn-reference-conformance into main

Align kaniko to Public Sector reference conformance standards

What this MR does and why

This MR closes the conformance gaps the recent reference audit surfaced. Each commit is one standard alignment; together they make kaniko a participating consumer of gitlab-com/public-sector/reference at v1.1.0. The adoption phase declared in .reference.yaml is report: conformance gaps surface in pipeline output but do not fail the job, so this MR can land without forcing a remediation cascade.

Standards now satisfied

Standard Before After
conformance-config no .reference.yaml declares reference_version: v1.1.0, adoption_phase: report, applicable_standards: all, empty exemptions
code-of-conduct no CODE_OF_CONDUCT.md one-paragraph file linking to the GitLab Community CoC
agents-md no AGENTS.md, CLAUDE.md, or .ai/ tree AGENTS.md + CLAUDE.md (one-line redirect) + .ai/{git,commits,merge-requests,ci-cd,standards}.md
contributing DCO link missing, no Government-Work: / AI-Assisted: trailers, no OFAC line, no scope-first onboarding re-issued from standards/contributing/templates/CONTRIBUTING.md with kaniko-local sections preserved verbatim
posture (link) no link to the compliance matrix one line above the lede pointing at gitlab-com.gitlab.io/public-sector/reference/compliance/

What was lifted versus adapted

Lifted verbatim (or near-verbatim) from the reference:

  • CODE_OF_CONDUCT.md -- one-paragraph file, no kaniko-specific text
  • CLAUDE.md -- @import AGENTS.md
  • .ai/git.md -- namespace-wide DCO/branch/remote/tag conventions; the only kaniko-specific addition is the "push rules in effect" footer naming the DCO + signed-commit + Conventional Commits prefix rules
  • .ai/merge-requests.md -- voice and codeowner rules; the matched paths section names Dockerfile.*, .gitlab-ci.yml, and patches/ instead of reference paths
  • CONTRIBUTING.md sign-offs, federal-employee, AI-assisted, OFAC, commit-message, MR sections -- all lifted from standards/contributing/templates/CONTRIBUTING.md

Adapted to kaniko's shape:

  • .reference.yaml -- adoption phase set to report (kaniko reports against standards but is not yet a strict conformer)
  • AGENTS.md -- reflects kaniko's actual shape (CI + Dockerfiles + patches + Pages site, no standards prose to navigate)
  • .ai/commits.md -- the Conventional Commits prefix is required (kaniko's push rule enforces it; the reference accepts both forms)
  • .ai/ci-cd.md -- describes kaniko's seven-variant matrix, the GOFIPS140 build-arg, and the Renovate-driven release cadence
  • .ai/standards.md -- names kaniko's reference posture (consumer, report phase, not in audited fleet) and the routing rule that decides where a change belongs
  • CONTRIBUTING.md license footer -- Apache-2.0 (inherited from chainguard-forks/kaniko), not the template's MIT default

What kaniko-specific content was preserved (verbatim)

The kaniko-local sections of the prior CONTRIBUTING.md were merged back in without rewording:

  • Adding or modifying a variant -- the four-Dockerfile recipe (lines verified diff-clean against the prior file)
  • Upstream sync (chainguard-forks/kaniko) -- the five-step Renovate-driven sync protocol (diff-clean)
  • Security response -- the four-layer vulnerability triage (diff-clean)

One new kaniko-local section was added (Patch refresh discipline) because the audit listed it as expected content. The substance previously lived on the Pages site (site/index.html, "Patch refresh on every upstream tag"); it now lives in CONTRIBUTING.md as well, naming the upstream-PR constraint and the tag-bump refresh contract.

.ai/ topic file subset

The reference's .ai/ tree carries seven topic files. This MR lifts five: git.md, commits.md, merge-requests.md, ci-cd.md, standards.md. Skipped:

  • design.md -- kaniko consumes design (badge row, brand band, hero composition) from the reference's repository and design standards; it does not author design.
  • compliance.md -- kaniko is not in the audited compliance fleet (no posture standard adoption beyond linking the matrix from the README).

If a future change brings kaniko into the audited fleet, compliance.md lifts straight from the reference.

Decisions to sanity-check

  1. LICENSE-docs was skipped. The reference standard standards/repository/check.sh does not require LICENSE-docs; the file is optional. kaniko's license is Apache-2.0 (inherited from chainguard-forks/kaniko), and the reference's LICENSE-docs is structured around MIT-code + CC-BY-SA-prose -- a mechanical lift would require re-authoring the file for kaniko's license posture. Surfacing the decision here for review rather than adding the file unilaterally.
  2. Adoption phase set to report rather than cutover. kaniko has not yet remediated every standard the reference publishes (e.g., it does not have a compliance topic file, does not declare a posture row, has not formally audited the brand artifacts against the latest repository SKILL.md). report lets this MR land without cascading remediation; the phase can flip to cutover in a follow-up once the audit converges.
  3. Conventional Commits in .ai/commits.md. kaniko's push rule enforces the CC prefix; the reference does not. The topic file calls out the difference at the top so future contributors are not surprised. If kaniko's push rule is intended to relax (matching the reference), the .ai/commits.md text adjusts in a follow-up.
  4. .ai/standards.md lists conformance-config as a project-shape standard. The reference's .ai/standards.md does not enumerate conformance-config because the reference cannot self-apply it. kaniko's .ai/standards.md does enumerate it, since kaniko is the consumer side. Surfacing in case the routing table should match the reference more strictly.

Files added (10)

  • .reference.yaml
  • CODE_OF_CONDUCT.md
  • AGENTS.md
  • CLAUDE.md
  • .ai/git.md
  • .ai/commits.md
  • .ai/merge-requests.md
  • .ai/ci-cd.md
  • .ai/standards.md

Files modified (2)

  • CONTRIBUTING.md -- re-issued from template with kaniko-local sections preserved verbatim
  • README.md -- one-line compliance matrix link above the lede

Commits (in order, off main)

3a37371 feat: add .reference.yaml for conformance-config standard
f85c386 feat: add CODE_OF_CONDUCT.md citing GitLab Community CoC
a40b942 feat: add AGENTS.md + CLAUDE.md + .ai/ topic dispatch
d7b21c9 feat: re-issue CONTRIBUTING.md from reference template
4f076dc docs: link compliance matrix from README

Each commit carries:

  • Signed-off-by: Andrew Dunn <andunn@gitlab.com>
  • Changelog: trailer (added/changed)
  • AI-Assisted: yes + AI-Tools: Claude Code
  • Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Test plan

  • glab ci lint .gitlab-ci.yml (no CI changes in this MR, but the pre-push convention applies)
  • Verify .reference.yaml parses (YAML syntax)
  • Verify the README compliance link resolves once the reference's compliance matrix is published at the named URL
  • Skim the new .ai/ files for any kaniko-specific claim that drifted from the actual code (Dockerfile variants, push rule shape, Renovate scope)
  • Confirm the CONTRIBUTING.md merge preserved the variant/upstream-sync/security-response sections without rewording (compare to git show HEAD~3:CONTRIBUTING.md)

References

Merge request reports