ci: supply-chain hardening (gitleaks, Dependabot, zizmor) + develop/main branch model (#120)

* ci: supply-chain & secrets hardening — gitleaks, Dependabot, zizmor (#117)

Adds the three cross-cutting gates from #117 on top of RigForge's existing
SHA-pinned actions and commit-verified XMRig build. Scope is only the gaps,
not a redo of that work.

- gitleaks: new Security workflow scans the full git history for committed
  secrets (pool creds, tokens, the #113 stratum access-password) on every push
  and PR, with a matching pre-commit hook. Binary is version+checksum pinned,
  mirroring the shellcheck/shfmt installs.
- Dependabot: .github/dependabot.yml for the github-actions ecosystem only
  (RigForge has no pip/npm/docker deps) — keeps the action pins current and
  surfaces advisories.
- zizmor: audits the workflows for template injection, over-broad GITHUB_TOKEN,
  and credential persistence. Hardened ci.yml/release.yml to a read-only default
  token and persist-credentials: false on checkout so the audit is clean.

The broader pre-commit hook set (shellcheck/shfmt/yamllint/markdownlint +
freebies) is left to #118, which extends .pre-commit-config.yaml.

Validated locally: gitleaks clean over full history, zizmor reports no findings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(security): enable zizmor online audits + weekly schedule

Run zizmor with online audits on (its default) so the known-vulnerable-actions
audit cross-references the actions we pin against the GitHub Advisory Database —
a CVE disclosed against a pinned action now fails the gate, not just structural
issues. GH_TOKEN is the built-in read-only token (advisory data is public; it's
only for API access).

Add a weekly schedule so a freshly-published advisory trips against main even
with no open PRs (the online audit is time-varying by design). gitleaks is
skipped on the scheduled tick — history doesn't change between pushes.

Complements Dependabot: zizmor blocks the merge, Dependabot opens the bump.
Validated: zizmor online reports no findings against the current pins.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: adopt the develop/main branch model (mirrors Pithead)

Pithead uses develop as the default integration branch and main as the release
branch; mirror that here (develop is now the repo default).

- ci.yml + security.yml: run on push to [main, develop] (PRs already run on any
  base via the unfiltered pull_request trigger).
- coverage: diff-cover now compares against the PR's actual base branch
  (github.base_ref, falling back to the pushed branch) instead of a hardcoded
  origin/main — so patch coverage stays correct once develop diverges from main.
- CONTRIBUTING: document the two-branch model; PRs target develop.
- RELEASING: build the release commit on develop, fast-forward into main, tag
  from main. develop is merged to main at each release (1.1 onward).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: VijitSingh97

.github/dependabot.yml

@@ -0,0 +1,22 @@
+# Keep the SHA-pinned GitHub Actions current. Dependabot bumps the commit pin AND the trailing
+# "# vX.Y.Z" comment together, and opens PRs for any security advisories affecting an action we use.
+#
+# Scope is github-actions ONLY (#117): RigForge is pure shell — no pip, npm, or docker ecosystems
+# to track. The XMRig source is pinned by version+commit and verified at build time, not via a
+# package manager, so it isn't a Dependabot ecosystem either.
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # github-actions ecosystem watches .github/workflows/
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci" # -> "ci(deps): bump actions/checkout ..."
+      include: "scope"
+    labels:
+      - "infra"
+    groups:
+      # One rollup PR for all action bumps rather than one-per-action — low-noise for a repo this small.
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/ci.yml

@@ -2,9 +2,15 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, develop] # develop is the integration branch; main is the release branch
   pull_request:
 
+# Least privilege: every job here only reads the repo to lint/test/build — nothing publishes or
+# writes. Set the floor once at the top so all jobs inherit a read-only GITHUB_TOKEN (zizmor:
+# excessive-permissions).
+permissions:
+  contents: read
+
 jobs:
   lint:
     name: Lint (shellcheck + shfmt)
@@ -16,6 +22,8 @@ jobs:
       SHFMT_SHA256: "fb096c5d1ac6beabbdbaa2874d025badb03ee07929f0c9ff67563ce8c75398b1"
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false # no pushes from CI; don't leave the token in .git/config (zizmor: artipacked)
       # Install PINNED, checksum-verified shellcheck + shfmt instead of the runner's preinstalled
       # builds, so lint/format results are reproducible and don't drift with the runner image (#6).
       # Downloaded straight from the upstream releases — no `apt-get update`, avoiding the mirror
@@ -46,6 +54,8 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false # zizmor: artipacked
       # Ubuntu is RigForge's supported target. The suite still exercises the macOS code path here via
       # stubs (OS_TYPE=Darwin + faked sysctl), so the macOS config profile is covered without a Mac
       # runner; contributors on macOS can also run `make test` locally. jq is preinstalled on the runner.
@@ -57,6 +67,8 @@ jobs:
     runs-on: macos-14 # Apple silicon; pinned (not macos-latest) to avoid image drift
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false # zizmor: artipacked
       # The Linux job only SIMULATES macOS (STUB_UNAME_S=Darwin + stubbed sed/launchctl). Here the suite
       # runs on real macOS, natively exercising the Darwin paths — BSD `sed` (the donate.h patch), the
       # macOS config profile, `mac_*` process control + the launchd login agent, and BSD `tar`/`date`
@@ -79,6 +91,8 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false # zizmor: artipacked
       # Runs the real script end-to-end inside a disposable Ubuntu container (RigForge's documented
       # Linux target), exercising the genuine Linux deploy path and /etc idempotency with real tools.
       - name: Run end-to-end suite
@@ -91,12 +105,16 @@ jobs:
       # Pin diff-cover (the patch-coverage gate); kcov + jq are pinned inside tests/coverage.sh.
       DIFF_COVER_VERSION: "10.3.0"
       PATCH_COVERAGE_MIN: "90" # new/changed lines in rigforge.sh + util must be this % covered
+      # Diff the PR against the branch it targets (develop or main). On a push, github.base_ref is empty,
+      # so fall back to the pushed branch itself — that's an empty diff that trivially passes.
+      BASE_REF: ${{ github.base_ref || github.ref_name }}
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          fetch-depth: 0 # diff-cover needs history to diff the PR against origin/main
+          fetch-depth: 0 # diff-cover needs history to diff the PR against its base branch
+          persist-credentials: false # the fetch below is read-only on a public repo (zizmor: artipacked)
       - name: Fetch base branch for diff-cover
-        run: git fetch --no-tags origin main
+        run: git fetch --no-tags origin "$BASE_REF"
       # Runs tests/run.sh under a digest-pinned kcov image, reports rigforge.sh + util/proposed-grub.sh
       # coverage, and fails if the total drops below the committed floor (tests/coverage-floor.txt).
       - name: Measure coverage (kcov) + enforce the total floor
@@ -106,4 +124,4 @@ jobs:
       - name: Install pinned diff-cover
         run: pipx install "diff-cover==${DIFF_COVER_VERSION}"
       - name: Enforce patch coverage on changed lines
-        run: diff-cover coverage/cobertura.xml --compare-branch=origin/main --fail-under="${PATCH_COVERAGE_MIN}"
+        run: diff-cover coverage/cobertura.xml --compare-branch="origin/$BASE_REF" --fail-under="${PATCH_COVERAGE_MIN}"

.github/workflows/release.yml

@@ -22,6 +22,10 @@ jobs:
       TAG: ${{ github.ref_name }}
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          # Releasing goes through `gh` with GH_TOKEN below, not `git push`, so the checkout never
+          # needs the token left in .git/config (zizmor: artipacked).
+          persist-credentials: false
 
       - name: Verify the tag matches VERSION
         run: |

.github/workflows/security.yml

@@ -0,0 +1,75 @@
+name: Security
+
+# Supply-chain & secrets gates (#117):
+#   - gitleaks: scan the full git history for committed secrets (pool creds, the stratum
+#     access-password from #113, tokens) on every push and PR.
+#   - zizmor: static-audit the GitHub Actions workflows themselves (template injection,
+#     over-broad GITHUB_TOKEN, unpinned actions, credential persistence) AND cross-reference the
+#     actions we pin against the GitHub Advisory Database (online audit).
+# Dependabot (github-actions) lives in .github/dependabot.yml; the matching gitleaks pre-commit
+# hook lives in .pre-commit-config.yaml.
+
+on:
+  push:
+    branches: [main, develop] # develop is the integration branch; main is the release branch
+  pull_request:
+  # Re-audit main on a schedule so a newly-published advisory against an action we pin trips the gate
+  # even during quiet periods with no pushes — the online zizmor audit is time-varying by design.
+  schedule:
+    - cron: "0 7 * * 1" # Mondays 07:00 UTC
+
+# Both jobs only read the tree to scan it. Pin the floor to read-only (zizmor: excessive-permissions).
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-24.04
+    # The weekly tick exists for zizmor's advisory re-audit; history doesn't change between pushes, so
+    # there's nothing new for gitleaks to scan on a schedule.
+    if: github.event_name != 'schedule'
+    env:
+      # Pinned + checksum-verified, same as the shellcheck/shfmt installs in ci.yml — reproducible and
+      # immune to runner-image drift. Keep GITLEAKS_VERSION in lockstep with .pre-commit-config.yaml.
+      GITLEAKS_VERSION: "8.30.1"
+      GITLEAKS_SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0 # scan EVERY commit, not just the tip — a secret is still a leak once pushed
+          persist-credentials: false # zizmor: artipacked
+      - name: Install pinned gitleaks
+        run: |
+          set -euo pipefail
+          tarball="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          curl -fsSL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${tarball}" -o "$tarball"
+          echo "${GITLEAKS_SHA256}  ${tarball}" | sha256sum -c -
+          tar -xzf "$tarball" gitleaks
+          sudo install gitleaks /usr/local/bin/gitleaks
+          gitleaks version
+      # Full-history scan with the built-in ruleset. --redact keeps any match out of the public logs;
+      # the job still fails (non-zero exit) so a leak blocks the merge.
+      - name: Scan git history for secrets
+        run: gitleaks git . --redact --no-banner --verbose
+
+  zizmor:
+    name: Workflow audit (zizmor)
+    runs-on: ubuntu-24.04
+    env:
+      ZIZMOR_VERSION: "1.25.2"
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false # zizmor: artipacked
+      # pipx is preinstalled on ubuntu-24.04; same install path as diff-cover in ci.yml's coverage job.
+      - name: Install pinned zizmor
+        run: pipx install "zizmor==${ZIZMOR_VERSION}"
+      # Online audits ON (zizmor's default): GH_TOKEN lets the `known-vulnerable-actions` audit query
+      # the GitHub Advisory Database, so a CVE disclosed against an action we pin fails the gate. The
+      # built-in token (read-only here) is enough — advisory data is public; it's only for API access.
+      # This complements Dependabot: zizmor blocks the merge, Dependabot opens the bump.
+      - name: Audit GitHub Actions workflows
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: zizmor .github/workflows/

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+# RigForge pre-commit hooks. Install once per clone:
+#
+#   pipx install pre-commit   # or: pip install pre-commit
+#   pre-commit install
+#
+# Scope here is the secret-scanning gate from #117: gitleaks, pinned to the SAME version CI runs
+# (.github/workflows/security.yml) so local catches a leak before it's ever pushed. The broader
+# hook set — shellcheck, shfmt, yamllint, markdownlint, and the freebies — is tracked in #118 and
+# will be added to this file, keeping the Makefile's SHELL_FILES the source of truth.
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1 # keep in lockstep with GITLEAKS_VERSION in .github/workflows/security.yml
+    hooks:
+      - id: gitleaks

CHANGELOG.md

@@ -7,6 +7,22 @@ All notable changes to RigForge are documented here. The format is based on
 
 ## [Unreleased]
 
+### Added
+- **Supply-chain & secret-scanning CI gates (#117).** Three cross-cutting hardening gates on top of
+  the existing SHA-pinned actions and commit-verified XMRig build:
+  - **gitleaks** — a new `Security` workflow scans the full git history for committed secrets (pool
+    credentials, tokens, the stratum access-password) on every push and PR, plus a matching
+    [`.pre-commit-config.yaml`](./.pre-commit-config.yaml) hook so a leak is caught before it's pushed.
+    The binary is version- and checksum-pinned, like the existing shellcheck/shfmt installs.
+  - **Dependabot** ([`.github/dependabot.yml`](./.github/dependabot.yml)) — keeps the hand-pinned
+    GitHub Actions current (`github-actions` ecosystem only; RigForge has no pip/npm/docker deps) and
+    surfaces action security advisories.
+  - **zizmor** — static-audits the workflows for template injection, over-broad `GITHUB_TOKEN`, and
+    credential persistence, and (online) cross-references the actions we pin against the GitHub
+    Advisory Database. Runs on push/PR plus a weekly schedule, so a CVE disclosed against a pinned
+    action trips the gate even with no open PRs. Hardened the existing `ci.yml`/`release.yml` to a
+    read-only default token and `persist-credentials: false` on checkout to make the audit clean.
+
 ## [1.0.1] - 2026-06-13
 
 ### Fixed

CONTRIBUTING.md

@@ -31,11 +31,30 @@ RigForge is portable Bash that has to run on Ubuntu/Debian and macOS, so:
   `shfmt` formatting.)
 - Update the README or other docs when you change behaviour or add options.
 
+## Secret scanning
+
+CI runs [gitleaks](https://github.com/gitleaks/gitleaks) over the full history on every push and PR,
+so an accidentally committed token or pool credential blocks the merge. Catch it locally first by
+installing the pre-commit hook (it runs the same pinned gitleaks on staged changes):
+
+```bash
+pipx install pre-commit   # or: pip install pre-commit
+pre-commit install
+```
+
+## Branching
+
+RigForge uses a two-branch model (same as [Pithead](https://github.com/p2pool-starter-stack/pithead)):
+
+- **`develop`** — the default, integration branch. All PRs target `develop`.
+- **`main`** — the release branch. `develop` is merged into `main` at each release, and version tags
+  are cut from `main`.
+
 ## Submitting a pull request
 
-1. Fork the repo and create a topic branch off `main`.
+1. Fork the repo and create a topic branch off `develop`.
 2. Make your change and confirm `shellcheck` passes.
-3. Open a PR against `main` and fill out the template.
+3. Open a PR against `develop` and fill out the template.
 4. **All PRs require review** before merging — a code owner will take a look.
 
 Keep PRs focused and the description clear about *what* changed and *why*. Small,

RELEASING.md

@@ -14,7 +14,11 @@ From `1.0.0` on, the `config.json` and CLI surface is stable — a breaking chan
 
 ## Cutting a release
 
-1. Ensure `main` is green: `make test` (and `make test-e2e` if Docker is available).
+Work lands on **`develop`** (the integration branch); a release is the point where `develop` is
+promoted to **`main`** and tagged. The steps below build the release commit on `develop`, merge it to
+`main`, and tag from `main`.
+
+1. Ensure `develop` is green: `make test` (and `make test-e2e` if Docker is available).
 2. **Full real-hardware e2e (the release gate).** CI exercises everything it can (lint, the
    dependency-free suite, the Docker `/etc` e2e, the coverage gate) — but it can't compile XMRig,
    reserve HugePages, write MSRs, set the governor, or actually hash. So on a **real Linux rig**, run
@@ -39,11 +43,16 @@ From `1.0.0` on, the `config.json` and CLI surface is stable — a breaking chan
 3. In [`CHANGELOG.md`](./CHANGELOG.md), move the `## [Unreleased]` entries under a new
    `## [X.Y.Z] - YYYY-MM-DD` heading, then leave a fresh empty `## [Unreleased]` above it.
 4. Bump [`VERSION`](./VERSION) to `X.Y.Z`.
-5. Commit the two together:
+5. Commit the two together on `develop`:
    ```bash
    git commit -am "release: vX.Y.Z"
+   git push origin develop
+   ```
+6. Promote `develop` to `main`:
+   ```bash
+   git checkout main && git merge --ff-only develop && git push origin main
    ```
-6. Tag and push (annotated tag, **matching `VERSION`**):
+7. Tag and push from `main` (annotated tag, **matching `VERSION`**):
    ```bash
    git tag -a vX.Y.Z -m "RigForge vX.Y.Z"
    git push origin main --follow-tags

SECURITY.md

@@ -37,6 +37,19 @@ sudo ufw deny 8080/tcp          # block it outright …
 sudo ufw allow from <DASHBOARD_IP> to any port 8080 proto tcp   # … or scope it to one host
 ```
 
+## Supply chain & secret scanning
+
+RigForge is built to be reproducible and tamper-evident:
+
+- **Pinned, verified inputs.** XMRig is cloned at a pinned commit and verified against a hardcoded
+  hash before it builds; GitHub Actions are SHA-pinned; CI tool installs (shellcheck, shfmt, gitleaks)
+  are version- and checksum-verified. **Dependabot** keeps the action pins current and flags advisories.
+- **Secret scanning.** [gitleaks](https://github.com/gitleaks/gitleaks) scans the full git history on
+  every push and PR, and runs as a pre-commit hook, so credentials can't slip into the repo.
+- **Workflow auditing.** [zizmor](https://github.com/zizmorcore/zizmor) static-audits the CI workflows
+  for template injection, over-broad token scopes, and credential persistence; jobs run with a
+  least-privilege, read-only `GITHUB_TOKEN` by default.
+
 ## Supported versions
 
 Only the latest `main` is supported. Please reproduce against current `main`