ci: add missing workflow permissions and widen the action-pin check

.github/workflows/issues-add-labels.yaml

@@ -1,4 +1,7 @@
 name: Label issues
+
+permissions:
+  contents: read
 on:
   issues:
     types:

.github/workflows/issues-add-to-project.yml

@@ -1,5 +1,8 @@
 name: Add issues to project
 
+permissions:
+  contents: read
+
 on:
   issues:
     types:
@@ -12,6 +15,8 @@ jobs:
   add-to-project:
     name: Add issue to project
     runs-on: ubuntu-latest
+    # Authenticates with ADD_TO_PROJECT_PAT, so the workflow GITHUB_TOKEN needs no scopes.
+    permissions: {}
     steps:
       - uses: actions/add-to-project@244f685bbc3b7adfa8466e08b698b5577571133e # v1.0.2
         with:

.github/workflows/update-action-pins.yml

@@ -1,9 +1,13 @@
 name: Update Action Pins
 
+permissions:
+  contents: read
+
 on:
   pull_request:
     paths:
       - ".github/workflows/**"
+      - ".github/actions/**"
 
 jobs:
   check-pins:
@@ -15,13 +19,13 @@ jobs:
           persist-credentials: false
       - name: Verify all actions are pinned to a SHA
         run: |
-          unpinned=$(grep -rE '^\s+(- )?uses: ' .github/workflows/ \
+          unpinned=$(grep -rhE '^\s+(- )?uses: ' .github/ \
             | grep -vE '^\s+(- )?uses: \.\/' \
             | grep -vE '@[0-9a-f]{40}($|\s)' || true)
           if [[ -n "$unpinned" ]]; then
             echo "::error::Found unpinned GitHub Actions (must use SHA digest, not tag):"
             echo "$unpinned"
             echo ""
-            echo "Run 'GITHUB_TOKEN=\$(gh auth token) update-action-pins .github/workflows/' to fix."
+            echo "Run 'GITHUB_TOKEN=\$(gh auth token) update-action-pins .github/workflows/ .github/actions/' to fix."
             exit 1
           fi

README.md

@@ -160,7 +160,7 @@ jobs:
     steps:
       - uses: actions/checkout@<40-char-sha> # v7
       - name: Set up nix
-        uses: opendefensecloud/dev-kit/.github/actions/setup-nix@<40-char-sha> # v2.1.0
+        uses: opendefensecloud/dev-kit/.github/actions/setup-nix@<40-char-sha> # <tag>
         with:
           cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
           cachix-signing-key: ${{ secrets.CACHIX_SIGNING_KEY }}

docs/NEW_REPO.md

@@ -48,9 +48,11 @@ See the README for the full list of `REPO_*` variables.
 The following secrets must be whitelisted for your repository at the organization level
 (Settings > Secrets and variables > Actions > Repository access):
 
-| Secret               | Used by                            |
-| -------------------- | ---------------------------------- |
-| `ADD_TO_PROJECT_PAT` | `issues-add-to-project` workflow   |
+| Secret                | Used by                                            |
+| --------------------- | -------------------------------------------------- |
+| `ADD_TO_PROJECT_PAT`  | `issues-add-to-project` workflow                   |
+| `CACHIX_AUTH_TOKEN`   | any job using the `setup-nix` action (see below)   |
+| `CACHIX_SIGNING_KEY`  | any job using the `setup-nix` action (see below)   |
 
 If your project uses private runners, whitelist the repository in the runner group settings
 (Settings > Actions > Runner groups).
@@ -65,9 +67,33 @@ Copy the relevant workflows from `.github/workflows/` in this repository:
 | `issues-add-labels.yaml`        | Automatically adds `needs-triage` label to new issues   |
 | `issues-add-to-project.yml`     | Adds new issues and PRs to the org project board        |
 | `release-drafter.yaml`          | Drafts release notes from merged PRs                    |
+| `update-action-pins.yml`        | Fails the PR if any action is not pinned to a SHA       |
 
 If using release-drafter, also copy `.github/release-drafter.yml` (the config file).
 
+### Nix-based CI
+
+Jobs that run inside the dev shell should use the shared `setup-nix` composite action
+rather than installing Nix themselves. It installs Nix and enables the org Cachix cache in
+two steps; secrets are not visible inside a composite action, so the caller passes them:
+
+```yaml
+    defaults:
+      run:
+        shell: nix develop --command bash -e {0}
+    steps:
+      - uses: actions/checkout@<40-char-sha> # v7
+      - name: Set up nix
+        uses: opendefensecloud/dev-kit/.github/actions/setup-nix@<40-char-sha> # <tag>
+        with:
+          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
+          cachix-signing-key: ${{ secrets.CACHIX_SIGNING_KEY }}
+      - run: make test
+```
+
+Both Cachix secrets are org-level (see step 4). On fork pull requests they are unavailable
+and cachix-action falls back to a read-only cache, which is the intended behaviour.
+
 If using commitlint (recommended), copy `.commitlintrc.yml` to your project root and enable the hook in `flake.nix`:
 
 ```nix