chore(ci): require approved issues or vouchers for PRs

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,9 @@
 
 ## Related issue
 
-<!-- Link an issue if there is one, for example: Fixes #123. -->
+<!-- Link the approved issue (labeled ready-for-contribution), e.g. Fixes #123.
+Maintainers, vouched contributors, and approved bots can skip this.
+Details: CONTRIBUTING.md#contribution-eligibility -->
 
 ## How did you check it?
 

.github/contribution-policy.json

@@ -0,0 +1,26 @@
+{
+	"vouchedContributors": [
+		{
+			"id": 44305048,
+			"login": "andrejsshell",
+			"reason": "Core team (usekaneo/developers)."
+		},
+		{
+			"id": 127273550,
+			"login": "randoneering",
+			"reason": "Core team (usekaneo/developers)."
+		},
+		{
+			"id": 176929823,
+			"login": "tinsever",
+			"reason": "Core team (usekaneo/developers)."
+		}
+	],
+	"exemptBots": [
+		{
+			"id": 49699333,
+			"login": "dependabot[bot]",
+			"reason": "Repository-managed dependency updates."
+		}
+	]
+}

.github/workflows/ci.yml

@@ -155,7 +155,7 @@ jobs:
       - name: Test release security controls
         run: |
           docker pull nginx:1.29.5-alpine
-          node --test scripts/security/*.test.mjs scripts/ci/*.test.mjs
+          node --test scripts/security/*.test.mjs scripts/ci/*.test.mjs scripts/contribution-eligibility/*.test.mjs
 
       - name: Run unit tests
         env:

.github/workflows/contribution-eligibility.yml

@@ -0,0 +1,64 @@
+name: Contribution eligibility
+
+on:
+  # zizmor: ignore[dangerous-triggers] Only executes policy code from main;
+  # never checks out or executes pull-request content.
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened, ready_for_review, closed]
+  issues:
+    types: [labeled, unlabeled, closed, reopened, deleted, transferred]
+  label:
+    types: [edited, deleted]
+  # zizmor: ignore[dangerous-triggers] Reads GitHub metadata and trusted main
+  # code only; does not consume artifacts or code from the triggering run.
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  push:
+    branches: [main]
+    paths:
+      - .github/contribution-policy.json
+      - .github/workflows/contribution-eligibility.yml
+      - scripts/contribution-eligibility/**
+  # Manual sidebar links and permission changes have no matching Actions event.
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  checks: write
+
+concurrency:
+  group: contribution-eligibility
+  cancel-in-progress: false
+
+jobs:
+  reconcile:
+    # Dependabot-triggered runs may receive a read-only token. CI completion
+    # rechecks its PR using a token issued in the trusted workflow context.
+    if: >-
+      (github.event_name != 'pull_request_target' || github.actor != 'dependabot[bot]') &&
+      (github.event_name != 'workflow_run' || github.event.workflow_run.actor.login == 'dependabot[bot]')
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    steps:
+      - name: Check out current trusted policy
+        uses: useblacksmith/checkout@25227e61ff9dafe400e22fa487b673eac4e4409a # v1
+        with:
+          # Always read the latest policy, including when an older run is queued.
+          ref: main
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24.19.0
+          package-manager-cache: false
+
+      - name: Check open pull requests
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: node scripts/contribution-eligibility/check.mjs

CONTRIBUTING.md

@@ -8,6 +8,7 @@ Thanks for wanting to contribute to Kaneo! Whether you're fixing bugs, adding fe
 - [Getting Started](#getting-started)
 - [Making Your First Contribution](#making-your-first-contribution)
   - [Finding Something to Work On](#finding-something-to-work-on)
+  - [Contribution Eligibility](#contribution-eligibility)
   - [The Process](#the-process)
 - [Development Guidelines](#development-guidelines)
   - [Code Style](#code-style)
@@ -36,9 +37,82 @@ Follow the [local development setup guide](ENVIRONMENT_SETUP.md) for prerequisit
 
 ### Finding Something to Work On
 
-- **Browse [open issues](https://github.com/usekaneo/kaneo/issues)** - look for "good first issue" labels
+- **Browse [issues ready for contribution](https://github.com/usekaneo/kaneo/issues?q=is%3Aissue%20is%3Aopen%20label%3Aready-for-contribution)** - the "good first issue" ones are a nice place to start
 - **Check our [Discord](https://discord.gg/rU4tSyhXXU)** - we often discuss features and bugs there
-- **Found a bug?** Feel free to fix it and open a PR
+- **Found a bug?** Open an issue first and wait for a maintainer to give the go-ahead before sending a PR (unless you're [exempt](#contribution-eligibility))
+
+### Contribution Eligibility
+
+Please talk to us before you start writing code. Find or open an issue and
+agree on the scope with a maintainer. Unless someone has vouched for you, your
+PR needs to link an open issue in this repo with the **`ready-for-contribution`**
+label. Opening an issue yourself isn't approval; a maintainer adds the label
+once the work is agreed.
+
+Link the issue in your PR description with `Fixes #123` or `Closes #123`.
+GitHub only picks those up for PRs against the default branch, so for other
+branches a maintainer can link the issue from the PR's Development sidebar.
+Just mentioning it (`See #123`) isn't enough.
+
+You can skip the issue if you're a repo admin, have the **maintain** role, have
+been vouched for, or are an approved bot. A voucher is tied to one GitHub
+account, can't be handed to someone else, and only skips the issue step.
+Everyone still goes through code review, CI, and the [AI policy](AI_POLICY.md).
+Past contributions or org membership don't earn a voucher automatically.
+
+The **Contribution eligibility** check on your PR tells you where you stand. If
+it fails, link an approved issue or ask a maintainer to vouch for you.
+
+The check reruns when you edit the PR description or push commits, when an
+issue gains or loses the label, and when the voucher list changes. It can't
+react to sidebar links or permission changes, so an hourly scheduled run picks
+those up (GitHub sometimes runs these late). Maintainers can also trigger the
+workflow by hand. Dependabot PRs are checked after their CI run finishes,
+because bot-triggered workflows may only get read-only tokens.
+
+Once the check is required, a failing result blocks merging. It won't stop
+anyone from opening a PR, and it never closes one.
+
+#### Managing Vouchers
+
+Vouchers live in
+[`.github/contribution-policy.json`](.github/contribution-policy.json). To vouch
+for someone, add them to `vouchedContributors` in a PR to `main`. To revoke,
+remove them. Review these changes the same way you'd review code.
+
+```json
+{
+  "id": 123456789,
+  "login": "example-contributor",
+  "reason": "Consistently submits focused changes and follows through on review."
+}
+```
+
+Get the numeric ID with `gh api users/USERNAME --jq '{id,login}'`. Only the ID
+matters for eligibility; `login` and `reason` are there so people can tell who
+it is and why. That way a renamed account keeps its voucher, and whoever grabs
+an old username doesn't inherit it.
+
+Bots go in `exemptBots`. For now that's just Dependabot.
+
+To turn on enforcement once this workflow is on `main`:
+
+1. Create the `ready-for-contribution` label and only put it on work you've agreed to.
+2. Run the **Contribution eligibility** workflow once so it checks PRs that are already open.
+3. In the branch rules for `main`, require the **Contribution eligibility**
+   status check with GitHub Actions as the source. Do the same for any other
+   protected branches people contribute to. Don't pick the workflow's
+   `reconcile` job: the script publishes its own check on each PR's head
+   commit, and that's the one to require.
+
+The automation only reads code and policy from `main`, relies on GitHub's own
+issue links, and never runs anything from the PR. Once it lists the open PRs
+and publishes pending checks, a broken policy or an eligibility lookup error
+fails the affected checks. If GitHub cannot list PRs or accept check updates,
+the workflow fails but earlier check results can remain unchanged, including
+successful ones. Maintainers must inspect failed workflow runs and rerun them
+after GitHub recovers before relying on those results. Revoking a voucher,
+removing the label, or closing the issue all trigger a recheck of open PRs.
 
 ### The Process
 
@@ -63,7 +137,8 @@ git commit -m "docs: update deployment guide"
 git push origin your-branch-name
 ```
 
-Then open a pull request on GitHub with a clear description of what you changed and why.
+Then open a pull request on GitHub that explains what you changed and why. Link
+the approved issue too, unless you're exempt.
 
 ## Development Guidelines
 
@@ -207,7 +282,7 @@ Please read and follow our [AI Contribution Policy](AI_POLICY.md), which adopts
 
 ## Types of Contributions We Love
 
-- **Bug fixes** - Found something broken? Fix it!
+- **Bug fixes** - Found something broken? Open an issue so we can agree on the fix
 - **New features** - Have an idea? Let's discuss it first
 - **Documentation** - Help others understand how to use Kaneo
 - **Performance improvements** - Make things faster

scripts/ci/README.md

@@ -31,6 +31,15 @@ upgrade-rendering regression checks. Configure the new job checks as required in
 GitHub if they should block merging; editing workflows alone does not change
 branch protection.
 
+**Contribution eligibility** is a separate workflow. It posts a status on the
+head commit of every open PR. Maintainers, vouched accounts, and approved bots
+pass without an issue; everyone else has to link an open
+`ready-for-contribution` issue from this repo. The workflow always takes its
+code and policy from `main`, never from the PR. Voucher management and the
+branch-rule setup are covered in
+[the contribution guide](../../CONTRIBUTING.md#contribution-eligibility). Run
+its tests with `node --test scripts/contribution-eligibility/*.test.mjs`.
+
 ## Local runtime checks
 
 Use disposable services only. The HTTP helpers refuse non-loopback origins.

scripts/contribution-eligibility/check-runs.mjs

@@ -0,0 +1,31 @@
+import { statusContext } from "./policy.mjs";
+
+export function checkPublisher(github) {
+  const ids = new Map();
+  return async (sha, result) => {
+    const body = {
+      name: statusContext,
+      status: result.state === "pending" ? "in_progress" : "completed",
+      ...(result.state === "pending"
+        ? {}
+        : { conclusion: result.state === "success" ? "success" : "failure" }),
+      details_url: `https://github.com/${github.repository}/blob/main/CONTRIBUTING.md#contribution-eligibility`,
+      output: {
+        title: result.description,
+        summary: `${result.description}\n\n[Contribution rules](https://github.com/${github.repository}/blob/main/CONTRIBUTING.md#contribution-eligibility).`,
+      },
+    };
+    const id = ids.get(sha);
+    const check = await github.request(
+      `repos/${github.repository}/check-runs${id ? `/${id}` : ""}`,
+      {
+        method: id ? "PATCH" : "POST",
+        body: id ? body : { ...body, head_sha: sha },
+      },
+    );
+    if (!Number.isSafeInteger(check.id) || check.id <= 0) {
+      throw new Error("GitHub did not return a check run ID.");
+    }
+    ids.set(sha, check.id);
+  };
+}

scripts/contribution-eligibility/check.mjs

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { GitHub } from "./github.mjs";
+import { checkPublisher } from "./check-runs.mjs";
+import { assessIssues, authorExemption, validatePolicy } from "./policy.mjs";
+
+async function checkPullRequest(github, pull, policy, policyError) {
+  if (policyError) throw policyError;
+  let exemption = authorExemption(pull.user, null, policy);
+  if (!exemption && pull.user.type !== "Bot") {
+    const permission = await github.request(
+      `repos/${github.repository}/collaborators/${encodeURIComponent(pull.user.login)}/permission`,
+      { allowNotFound: true },
+    );
+    exemption = authorExemption(pull.user, permission, policy);
+  }
+  let result;
+  if (exemption) {
+    result = { state: "success", description: exemption };
+  } else {
+    result = assessIssues(await github.linkedIssues(pull.number));
+  }
+  const current = await github.request(
+    `repos/${github.repository}/pulls/${pull.number}`,
+  );
+  if (current.state !== "open") return null;
+  if (
+    current.head.sha !== pull.head.sha ||
+    current.body !== pull.body ||
+    current.base.ref !== pull.base.ref
+  ) {
+    return {
+      state: "pending",
+      description: "Pull request changed; waiting for a fresh check.",
+    };
+  }
+  return result;
+}
+
+export async function reconcile(github, loadPolicy) {
+  let policy;
+  let policyError;
+  try {
+    policy = validatePolicy(await loadPolicy());
+  } catch (error) {
+    policyError = error;
+  }
+  const pulls = await github.openPullRequests();
+  const heads = new Map();
+  const publish = checkPublisher(github);
+  for (const pull of pulls) {
+    if (!/^[a-f0-9]{40}$/.test(pull.head?.sha ?? "")) {
+      throw new Error("Missing pull request head commit.");
+    }
+    if (!heads.has(pull.head.sha)) {
+      // Clear earlier successes before reading mutable approval and trust data.
+      await publish(pull.head.sha, {
+        state: "pending",
+        description: "Checking contribution eligibility.",
+      });
+      heads.set(pull.head.sha, []);
+    }
+  }
+  const results = [];
+  const errors = [];
+  // Every event refreshes all open PRs: GitHub concurrency may replace a queued
+  // run, so an event scoped to one PR could otherwise leave another check stale.
+  for (const pull of pulls) {
+    let result;
+    try {
+      result = await checkPullRequest(github, pull, policy, policyError);
+    } catch (error) {
+      errors.push(error);
+      result = {
+        state: "error",
+        description:
+          "Eligibility could not be checked. A maintainer must rerun the workflow.",
+      };
+    }
+    if (result) {
+      const entry = { number: pull.number, ...result };
+      results.push(entry);
+      heads.get(pull.head.sha).push(entry);
+    }
+  }
+  // Checks belong to commits, not PRs. A vouched author's PR must never make
+  // a different, ineligible PR sharing the same commit eligible to merge.
+  const priority = ["error", "failure", "pending", "success"];
+  for (const [sha, entries] of heads) {
+    const worst = entries.toSorted(
+      (a, b) => priority.indexOf(a.state) - priority.indexOf(b.state),
+    )[0];
+    if (worst) {
+      await publish(sha, {
+        state: worst.state,
+        description: `PR #${worst.number}: ${worst.description}`,
+      });
+    }
+  }
+  if (policyError) errors.push(policyError);
+  if (errors.length)
+    throw new AggregateError(errors, "Contribution eligibility checks failed.");
+  return results;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const github = new GitHub(process.env);
+  const results = await reconcile(github, async () =>
+    JSON.parse(
+      await readFile(
+        new URL("../../.github/contribution-policy.json", import.meta.url),
+        "utf8",
+      ),
+    ),
+  );
+  for (const result of results) {
+    console.log(`PR #${result.number}: ${result.state}. ${result.description}`);
+  }
+}