From 9256d36164242fb13ee7c6677814d92ccf9f1357 Mon Sep 17 00:00:00 2001 From: Brian Lockwood Date: Fri, 28 Aug 2026 15:29:24 -0700 Subject: [PATCH] ci: check commit sign-off and signature on pull requests Neither requirement was actually enforced. `.github/dco.yml` configures the probot DCO app, but the app is not reporting checks on this repository, so a missing `Signed-off-by` trailer went unnoticed. The `required_signatures` rule on `main` is satisfied by the signature GitHub puts on the squash/merge commit it creates, not by the contributor's commits, so unsigned commits merged fine. 23 of the last 100 commits on `main` carry no sign-off. The docs were also silent on signing: CONTRIBUTING.md, AGENTS.md, the PR template and the first-time-contributor greeting all said `git commit -s` and never mentioned `-S`, even though `main` requires signed commits. Adds a Commit Requirements workflow that reads PR commit metadata through the API and, for every non-bot commit, requires a `Signed-off-by` trailer and a verified signature. It upserts a single comment naming each offending commit with the recovery commands and a link to CONTRIBUTING.md, and fails the job. It publishes no `ci-gate` check, so it is visible without blocking merges. Sign-off is checked for presence only, deliberately not matched against the commit author's email: GitHub's `NNN+user@users.noreply.github.com` aliases make that mismatch common and benign, and a check people learn to ignore enforces nothing. Also flips `.github/dco.yml` from `members: false` to `members: true`. That exemption pointed away from the actual problem, since 19 of the 23 recent sign-off misses are from maintainers. Signed-off-by: Brian Lockwood --- .claude/CLAUDE.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 4 +- .github/dco.yml | 13 +- .github/workflows/commit-requirements.yaml | 241 +++++++++++++++++++++ .github/workflows/welcome.yaml | 2 +- CONTRIBUTING.md | 111 ++++++++-- GOVERNANCE.md | 2 +- 7 files changed, 349 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/commit-requirements.yaml diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1f85b9115..81337a668 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -311,7 +311,7 @@ When choosing between approaches, prioritize: - **Vendoring**: Go deps are vendored. `make build`/`make test` pass `-mod=vendor` via `GOFLAGS`; `go get` is still fine but follow with `go mod vendor`. - **License headers**: every source file needs an Apache-2.0 header. `make license-fmt` (which runs as part of `make fmt`) shells out to [`addlicense`](https://github.com/google/addlicense) with `scripts/license-header.tmpl` — don't copy-paste headers by hand. It only **adds** headers to files that lack one; it never rewrites an existing header, so the copyright year is the year of first publication and is not bumped on edit (matching Google/Kubernetes practice). Files carrying a generated-code marker (`// Code generated … DO NOT EDIT.`) are skipped, which is a content check, not a filename check: a hand-written `zz_generated.*` would still get a header, and a generated file without the marker would too. `make license-header-check` is the CI gate; it fails if a tracked source file has no header, or has one that isn't `SPDX-License-Identifier: Apache-2.0`. New Go files get `//` line comments rather than the `/* */` block used by older files: a block comment above a `//go:build` constraint is not legal, so gofmt hoists the constraint and the two tools fight forever. -- **Commits**: Conventional Commits format, with DCO sign-off (`git commit -s`). No pseudonyms. +- **Commits**: Conventional Commits format. Every commit must be both signed off and cryptographically signed: `git commit -s -S`. `-s` adds the DCO `Signed-off-by` trailer, `-S` attaches the GPG/SSH signature that `main`'s `required_signatures` ruleset and the Commit Requirements workflow check for. They are independent, so neither flag substitutes for the other, and both are needed on amends too (`git commit --amend -s -S --no-edit`). Signing needs an unsandboxed shell. No pseudonyms. - **Docs are part of every PR.** If your change alters user-visible behavior (CRD field, CLI command/flag, env var, annotation, metric, lifecycle semantics, install/upgrade flow) or an architectural concept captured in `docs/`, update the affected doc page **in the same PR** — not a follow-up. If a doc page is wrong or stale because of your change, fix it. If your change makes an existing doc obsolete, delete the stale section rather than leaving two sources of truth. **A behavior-changing PR without a corresponding `docs/` update will be rejected in review** — treat this as a blocking requirement, not a nicety. Docs-only changes are fine on their own, but code changes without docs are not. - **`RELEASE_NOTES.md` is not a changelog, and most PRs do not belong in it.** Each component's `CHANGELOG.md` is generated from commit history and already records every change, so a hand-written note is duplication unless the reader has to **do** something or will be **surprised**: an action required at upgrade time, a deprecation with a deadline, a behavior they will notice and did not ask for, a new knob worth discovering. A bug fix that restores intended behavior needs no entry, however involved the fix was. Default to not adding one; the commit message and the linked issue carry the reasoning. Every entry that is only narrative makes the entries that matter harder to find. - **Container runtime**: the operator Makefile defaults to `podman` locally, `docker` in CI. Override via `DOCKER_CMD=docker`. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 738e45d2e..7c8975467 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,7 +4,7 @@ ## Checklist -- [ ] I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/skyhook/blob/main/CONTRIBUTING.md). -- [ ] My commits are signed off (`git commit -s`) per the [DCO](https://developercertificate.org/). +- [ ] I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/nodewright/blob/main/CONTRIBUTING.md). +- [ ] My commits are signed off per the [DCO](https://developercertificate.org/) **and** cryptographically signed: `git commit -s -S`. - [ ] New or existing tests cover these changes. - [ ] The documentation is up to date with these changes. diff --git a/.github/dco.yml b/.github/dco.yml index b1793a33d..f3b686d30 100644 --- a/.github/dco.yml +++ b/.github/dco.yml @@ -14,9 +14,14 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Configuration for the DCO bot (https://github.com/probot/dco), which enforces -# the Developer Certificate of Origin sign-off documented in CONTRIBUTING.md. +# Configuration for the DCO bot (https://github.com/probot/dco), kept in case the +# app is installed on this repository. It is currently not reporting any checks, +# so the sign-off requirement documented in CONTRIBUTING.md is enforced by +# .github/workflows/commit-requirements.yaml instead, which also checks the +# cryptographic signature the app does not look at. -# Require all commits to be signed off, except organization members and bots. +# Require every commit to be signed off, organization members included. Setting +# this to false exempts members, which is where most of the missing sign-offs on +# this repository have come from. require: - members: false + members: true diff --git a/.github/workflows/commit-requirements.yaml b/.github/workflows/commit-requirements.yaml new file mode 100644 index 000000000..397a6a4d1 --- /dev/null +++ b/.github/workflows/commit-requirements.yaml @@ -0,0 +1,241 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +name: Commit Requirements + +# Every commit must carry a DCO sign-off (`git commit -s`) and a verified +# cryptographic signature (`git commit -S`), both documented in CONTRIBUTING.md. +# Neither was actually checked before this workflow: `.github/dco.yml` only +# configures the probot DCO app, which is not reporting on this repository, and +# the `required_signatures` rule on `main` is satisfied by the signature GitHub +# puts on the squash/merge commit it creates, not by the contributor's commits. +# +# This job reports; it does not gate. It deliberately publishes no `ci-gate` +# check, so a red run here is visible without wedging the merge button. Promote +# it by adding a `ci-gate` job (see commit-linting.yaml) once the open-PR +# backlog is clean. +# +# pull_request_target is required to comment on pull requests from forks, which +# is where the violations come from. It is safe here for the usual reason: the +# job never checks out or executes the contributor's code, it only reads commit +# metadata through the API. + +on: + pull_request_target: + types: [opened, synchronize, reopened, ready_for_review] + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + commit-requirements: + name: Sign-off and signature + runs-on: ubuntu-latest + permissions: + pull-requests: write + timeout-minutes: 5 + steps: + - name: Check commits and report + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const MARKER = ''; + const CONTRIBUTING = `https://github.com/${context.repo.owner}/${context.repo.repo}/blob/main/CONTRIBUTING.md#developer-certificate-of-origin-and-commit-signing`; + const { owner, repo } = context.repo; + const number = context.payload.pull_request.number; + + const commits = await github.paginate(github.rest.pulls.listCommits, { + owner, repo, pull_number: number, per_page: 100, + }); + + // This endpoint tops out at 250 commits. Reporting success on a + // truncated list would clear a pull request nobody fully checked, so + // say so and fail instead. + const expectedCommits = context.payload.pull_request.commits; + const truncated = + typeof expectedCommits === 'number' && commits.length < expectedCommits; + + // Bots cannot run `git commit -s -S`; Renovate and Dependabot commits + // are signed by GitHub's own key and carry no sign-off by design. + // + // Keyed on the GitHub identity the API resolved, never on `commit.author`. + // The latter is git metadata the committer sets freely, so matching a + // `[bot]` name or noreply address there would let anyone skip both checks + // with a one-line `git config`. Dependabot and the github-actions app that + // runs Renovate here both resolve to `author.type === 'Bot'`. + const isBot = (c) => c.author?.type === 'Bot'; + + // Only the trailer block counts, matching `git interpret-trailers`: + // the last paragraph, and never a single-paragraph message. Scanning + // every line would accept a `Signed-off-by:` quoted in prose while git + // itself sees no trailer at all. + // + // Presence only, deliberately not matched against the commit author's + // email. GitHub hands out `NNN+user@users.noreply.github.com` aliases, + // so a contributor who signs off with their real address trips an + // author/trailer mismatch through no fault of their own. Flagging that + // is noise, and a check people learn to ignore enforces nothing. + const hasSignOff = (message) => { + const paragraphs = (message ?? '') + .replace(/\r/g, '') + .split(/\n[ \t]*\n/) + .filter((p) => p.trim().length > 0); + if (paragraphs.length < 2) return false; + // Anchored at column 0 and the paragraph is not trimmed: git does not + // treat an indented line as a trailer, so neither may this. + return paragraphs[paragraphs.length - 1] + .split('\n') + .some((line) => /^Signed-off-by:\s*.+<.+>\s*$/i.test(line)); + }; + + const checked = commits.filter((c) => !isBot(c)); + + const violations = []; + for (const c of checked) { + + const problems = []; + + if (!hasSignOff(c.commit.message)) { + problems.push('no `Signed-off-by` trailer (`git commit -s`)'); + } + + if (c.commit.verification?.verified !== true) { + const reason = c.commit.verification?.reason ?? 'unknown'; + problems.push(`signature not verified: \`${reason}\` (\`git commit -S\`)`); + } + + if (problems.length > 0) { + violations.push({ sha: c.sha, subject: c.commit.message.split('\n')[0], problems }); + } + } + + // Match the author as well as the marker. MARKER is an HTML comment, so + // anyone can paste it into a comment of their own; keying on the body + // alone would make a later run edit that comment instead of this + // workflow's, and the job holds `pull-requests: write`. + const existing = ( + await github.paginate(github.rest.issues.listComments, { + owner, repo, issue_number: number, per_page: 100, + }) + ).find( + (comment) => + comment.user?.login === 'github-actions[bot]' && comment.body?.includes(MARKER), + ); + + const upsert = async (body) => { + if (existing) { + await github.rest.issues.updateComment({ + owner, repo, comment_id: existing.id, body: `${MARKER}\n${body}`, + }); + } else { + await github.rest.issues.createComment({ + owner, repo, issue_number: number, body: `${MARKER}\n${body}`, + }); + } + }; + + if (truncated) { + const body = [ + '### ⚠️ Could not check every commit', + '', + `GitHub returned ${commits.length} of this pull request's ${expectedCommits} commits, so the sign-off and signature check is incomplete and is not reporting a pass.`, + '', + 'The pull request commits endpoint returns at most 250 commits. Splitting this into smaller pull requests, or rebasing to reduce the commit count, lets the check cover everything.', + '', + `The requirements themselves are unchanged and are described in [CONTRIBUTING.md](${CONTRIBUTING}).`, + ].join('\n'); + await upsert(body); + core.setFailed( + `Commit list truncated: got ${commits.length} of ${expectedCommits} commits.`, + ); + return; + } + + if (violations.length === 0) { + core.info(`All ${checked.length} non-bot commit(s) are signed off and signed.`); + if (existing) { + await upsert('✅ Every non-bot commit on this pull request is now signed off and signed. Thanks!'); + } + return; + } + + // The head ref is attacker-chosen and lands in bash blocks a maintainer + // is invited to copy-paste. `git check-ref-format` permits `;`, `$(...)`, + // backticks, `&&` and `|` in a branch name, so this must be quoted. + const shellQuote = (v) => "'" + String(v).replace(/'/g, "'\\''") + "'"; + const headRef = shellQuote(context.payload.pull_request.head.ref); + + const rows = violations + .map((v) => `| \`${v.sha.slice(0, 8)}\` | ${v.subject} | ${v.problems.join('
')} |`) + .join('\n'); + + await upsert([ + '### ❌ Some commits are missing a sign-off or a signature', + '', + 'Every commit in this repository must be **signed off** (`-s`, the [DCO](https://developercertificate.org/) certification that you wrote the patch) **and cryptographically signed** (`-S`, proving the commit came from you). They are independent; you need both, on every commit.', + '', + '| Commit | Subject | Problem |', + '| --- | --- | --- |', + rows, + '', + '
', + 'How to fix', + '', + 'One-time setup, so you only ever need `-s` from here on:', + '', + '```bash', + '# Commit identity, used in the Signed-off-by trailer.', + '# Use an address GitHub has verified on your account.', + 'git config user.name "Your Name"', + 'git config user.email "your.email@example.com"', + '', + '# Signing key, separate from the identity above. For SSH:', + 'git config gpg.format ssh', + 'git config user.signingkey ~/.ssh/id_ed25519.pub', + '', + '# Sign every commit from now on', + 'git config commit.gpgsign true', + '```', + '', + 'The key must also be registered with GitHub: see [generating a GPG or SSH signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification).', + '', + 'To fix the most recent commit:', + '', + '```bash', + 'git commit --amend -s -S --no-edit', + 'git push --force-with-lease origin ' + headRef, + '```', + '', + 'To fix every commit on the branch at once. Check for merge commits first, because a plain rebase drops them:', + '', + '```bash', + 'git log --oneline --merges origin/main..HEAD # empty output means linear', + '', + '# Linear branch:', + "git rebase --exec 'git commit --amend -s -S --no-edit' origin/main", + '', + '# Branch with merge commits, preserving them:', + "git rebase --rebase-merges --exec 'git commit --amend -s -S --no-edit' origin/main", + '```', + '', + 'Confirm the rewrite changed nothing but the signatures before pushing:', + '', + '```bash', + 'git range-diff @{u}...HEAD', + 'git push --force-with-lease origin ' + headRef, + '```', + '', + 'Re-signing rewrites every commit, which outdates inline review comments. If the PR is already under review, leave a note saying you force-pushed.', + '', + '
', + '', + `Full details are in [CONTRIBUTING.md](${CONTRIBUTING}). This check reports but does not block your merge; a maintainer will still ask you to fix it.`, + ].join('\n')); + + core.setFailed( + `${violations.length} of ${checked.length} non-bot commit(s) are missing a sign-off or a verified signature.`, + ); diff --git a/.github/workflows/welcome.yaml b/.github/workflows/welcome.yaml index 997f38063..0772ea55b 100644 --- a/.github/workflows/welcome.yaml +++ b/.github/workflows/welcome.yaml @@ -87,7 +87,7 @@ jobs: `Welcome to NodeWright, @${creator}! Thanks for your first pull request.`, '', 'Before review, please ensure:', - `- All commits are signed off per the [DCO](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/main/CONTRIBUTING.md) (\`git commit -s\`)`, + `- All commits are signed off **and** signed: \`git commit -s -S\` (see [CONTRIBUTING.md](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/main/CONTRIBUTING.md#developer-certificate-of-origin-and-commit-signing))`, '- Commits follow [Conventional Commits](https://www.conventionalcommits.org/)', '- CI checks pass (tests, lint, security scan)', '- The PR description explains the *why* behind your changes', diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 428953dc6..07816454d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,7 +49,7 @@ Reference the issue in your PR description (`closes #1234`) so it closes on merg 2. Make your changes and ensure tests pass (`make test` in the relevant component directory). 3. Run `make fmt` to format code and add license headers. 4. When you bump a Go or Python dependency, run `make notices` and commit the refreshed `THIRD_PARTY_NOTICES.md` files alongside your change. See [`docs/contributing/release-process.md`](docs/contributing/release-process.md) for the workflow. -5. Commit with a [Conventional Commits](https://www.conventionalcommits.org/) message and sign off (see below). +5. Commit with a [Conventional Commits](https://www.conventionalcommits.org/) message, signed and signed off: `git commit -s -S` (see [Developer Certificate of Origin and commit signing](#developer-certificate-of-origin-and-commit-signing)). 6. Open a pull request against `main`. The PR template will guide you through the checklist. ### Running the CI checks locally @@ -126,12 +126,100 @@ If you are changing NodeWright itself rather than writing a package: In every case, find the nearest existing example and match it. A new pattern that has no precedent in the target package should be called out explicitly in your PR description — what you introduced, why the existing patterns didn't fit, and why it should become the convention. -## Developer Certificate of Origin (DCO) +## Developer Certificate of Origin and commit signing -The sign-off is a simple line at the end of the explanation for the patch. Your -signature certifies that you wrote the patch or otherwise have the right to pass -it on as an open-source patch. The rules are pretty simple: if you can certify -the below (from [developercertificate.org](http://developercertificate.org/)): +Every commit, from every contributor and maintainers included, must be both **signed off** and **cryptographically signed**: + +```bash +git commit -s -S -m "your message" +``` + +- `-s` (lowercase) adds a `Signed-off-by` trailer, certifying the [Developer Certificate of Origin 1.1](#what-you-are-certifying) reproduced below. +- `-S` (uppercase) attaches a GPG or SSH signature, proving the commit came from you. + +The two are independent, and neither implies the other. Use both, on every commit. A branch ruleset enforces **Require signed commits** on `main`, and the [Commit Requirements](.github/workflows/commit-requirements.yaml) workflow comments on any pull request carrying a commit that is missing either one. + +The `Signed-off-by` trailer should name the commit author, and must be a real name: + +``` +Signed-off-by: Joe Smith +``` + +Sorry, no pseudonyms or anonymous contributions. + +What the automated check actually verifies is narrower than the rule above: for each commit not authored by a bot, that a `Signed-off-by` trailer is present and that the signature verified. It does not compare the trailer's address to the author's, because GitHub's `NNN+user@users.noreply.github.com` aliases make that mismatch common and harmless. Reviewers still enforce the rest. + +### One-time setup + +Do this once and `-S` becomes automatic, so the only flag you have to remember is `-s`. + +Your commit identity, which is what lands in the `Signed-off-by` trailer: + +```bash +git config user.name "Your Name" +git config user.email "your.email@example.com" +``` + +Use an address GitHub has verified on your account, otherwise GitHub will not mark the commit as verified. This is separate from your signing key and does not have to match it. + +Then a signing key, which GitHub must also know about. Follow GitHub's guide to [generate a GPG or SSH signing key and add it to your account](https://docs.github.com/en/authentication/managing-commit-signature-verification), then point git at it. For SSH: + +```bash +git config gpg.format ssh +git config user.signingkey ~/.ssh/id_ed25519.pub # the public key, not the private one +``` + +For GPG, leave `gpg.format` unset and use the key ID from `gpg --list-secret-keys --keyid-format=long`: + +```bash +git config user.signingkey +``` + +Finally, sign every commit without having to remember `-S`: + +```bash +git config commit.gpgsign true +``` + +### Forgot to sign or sign off? + +Fix the most recent commit and re-push: + +```bash +git commit --amend -s -S --no-edit +git push --force-with-lease origin your-branch +``` + +Fix every commit on the branch at once. Check first whether the branch contains merge commits, because a plain rebase drops them and takes any merge-only content with them: + +```bash +git log --oneline --merges origin/main..HEAD # empty output means the branch is linear +``` + +For a linear branch: + +```bash +git rebase --exec 'git commit --amend -s -S --no-edit' origin/main +``` + +For a branch with merge commits, preserve the topology: + +```bash +git rebase --rebase-merges --exec 'git commit --amend -s -S --no-edit' origin/main +``` + +Either way, confirm the rewrite changed nothing but the signatures before you push: + +```bash +git range-diff @{u}...HEAD +git push --force-with-lease origin your-branch +``` + +Re-signing rewrites every commit, which outdates the inline comments reviewers have already left. If the pull request is already under review, say on it that you force-pushed. + +### What you are certifying + +By signing off you certify the following, from [developercertificate.org](https://developercertificate.org/): ``` Developer Certificate of Origin @@ -172,17 +260,6 @@ By making a contribution to this project, I certify that: this project or the open source license(s) involved. ``` -Then you just add a line to every git commit message: - -``` -Signed-off-by: Joe Smith -``` - -Use your real name (sorry, no pseudonyms or anonymous contributions.) - -If you set your `user.name` and `user.email` git configs, you can sign your -commit automatically with `git commit -s`. - ## Code Style We use [Conventional Commits](https://www.conventionalcommits.org/) for our commit messages. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index ea0da378e..f762b8b10 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -21,7 +21,7 @@ NodeWright uses three roles. Code ownership maps directly to [`.github/CODEOWNER ### Contributors -Anyone who opens an issue, pull request, or discussion. Contributors follow the [Code of Conduct](CODE_OF_CONDUCT.md) and sign off their commits under the DCO (see [CONTRIBUTING.md](CONTRIBUTING.md)). No special access is required to contribute. +Anyone who opens an issue, pull request, or discussion. Contributors follow the [Code of Conduct](CODE_OF_CONDUCT.md) and both sign off and sign their commits, `git commit -s -S` (see [CONTRIBUTING.md](CONTRIBUTING.md#developer-certificate-of-origin-and-commit-signing)). No special access is required to contribute. ### Code Owners