fix: repo review improvements — governance docs, gitleaks, tooling

.github/workflows/gitleaks.yml

@@ -16,7 +16,7 @@ jobs:
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       RESPONSE_GUIDE_URL: https://github.com/CivicTechWR/.github/blob/main/docs/gitleaks-response.md
-      GITLEAKS_VERSION: v8.18.2
+      GITLEAKS_VERSION: v8.30.1
     steps:
       - name: Check out code
         uses: actions/checkout@v4

.gitignore

@@ -0,0 +1,11 @@
+# macOS
+.DS_Store
+
+# Editor / IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# AI tooling (local only)
+.qodo/

.gitleaks.toml

@@ -0,0 +1,18 @@
+title = "CivicTechWR Gitleaks Config"
+
+# Inherit all built-in Gitleaks detection rules.
+# Without this, a custom config file disables all default detectors.
+[extend]
+useDefault = true
+
+# Add allowlist entries below to suppress false positives.
+# Each entry should include a `description` explaining why it is safe.
+# Only add entries after confirming the value is not a real secret.
+#
+# Example:
+# [[allowlist.regexes]]
+# description = "Example placeholder API key in docs"
+# regex = "EXAMPLE_API_KEY_12345"
+
+[allowlist]
+description = "CivicTechWR global allowlist"

README.md

@@ -23,6 +23,11 @@ Default files that appear in all CivicTechWR repositories (unless overridden):
 
 - **profile/README.md** - Organization profile shown on the [CivicTechWR GitHub page](https://github.com/CivicTechWR)
 
+### Governance & Operations Docs
+
+- **docs/governance/codeowners-branch-protection.md** - Branch protection guidance, team roster, and break-glass procedure
+- **docs/gitleaks-response.md** - Secret scanning triage and remediation guide
+
 ## Why This Repository?
 
 GitHub automatically uses files in `.github` as defaults across all repositories in the organization. This ensures:

SECURITY.md

@@ -1,13 +1,8 @@
 # Security Policy
 
-## Supported Versions
+## Policy Maintenance
 
-This CivicTechWR project template is actively maintained. Security updates are provided for:
-
-| Version  | Supported          |
-| -------- | ------------------ |
-| Latest   | :white_check_mark: |
-| Previous | :x:                |
+This security policy is actively maintained by CivicTechWR organizers. It was last reviewed **November 14, 2025** and is scheduled for review **May 14, 2026**.
 
 ## Reporting a Vulnerability
 

docs/gitleaks-response.md

@@ -1,31 +1,36 @@
 # Gitleaks Response Guide
 
-This guide helps CivicTechWR maintainers triage, contain, and remediate potential secrets flagged by automated Gitleaks scans.
+When this workflow comments on your pull request, it means Gitleaks spotted something that looks like a credential. The build stays green, but secrets must be handled quickly and carefully.
 
-## 1. Triage the Finding
+## Quick Checklist
 
-- Review the redacted report attached to the workflow run or pull request comment to identify the file and rule triggered.
-- Decide whether the flagged value is a real secret, test data, or a false positive.
+1. **Stop merging** the pull request until the investigation is complete.
+2. Open the PR comment or downloaded `gitleaks-report.json` artifact to review the redacted findings.
+3. Confirm whether each finding is a real secret or a false positive.
+4. Follow the appropriate section below and leave a short update on the PR comment.
 
-## 2. Contain the Exposure
+## If the Secret Is Real
 
-- Remove the secret from the repository immediately (revert the change or follow up with a commit that deletes it and uses environment variables or secrets instead).
-- Rotate or invalidate the exposed credential in the affected service (Supabase, Slack, third-party API, etc.).
+- **Rotate / revoke the credential immediately.** Use the relevant provider console (Supabase, Slack, third-party API, etc.) or contact the owner of the secret.
+- **Purge the secret from Git history.** Remove it locally (including from previous commits) and force-push a clean branch.
+  - Prefer [`git filter-repo`](https://github.com/newren/git-filter-repo) (or `git filter-branch` as a fallback) to rewrite history.
+  - After rewriting history, regenerate the artifact (`git commit --amend` or new commit) and push with `--force-with-lease`.
+  - If the secret landed in commit history already merged to the default branch, coordinate with maintainers before rewriting — downstream forks may need notification.
+- **Document replacements.** Update `.env.example` or secrets management notes so others know the new credential.
+- **Confirm the fix.** Run `gitleaks detect --redact` locally to verify the repository is clean before merging.
+- **Update the PR comment.** Reply to the workflow comment summarizing what was rotated and how history was cleaned (no need to paste secrets).
+- **For high-impact secrets** (production credentials, user data access), escalate immediately in the organizers' channel or email `civictechwr@gmail.com`.
 
-## 3. Clean the History (If Needed)
+## If It Is a False Positive
 
-- If the secret landed in commit history, coordinate with maintainers before rewriting history.
-- Use `git filter-repo` or provider tooling to purge historical references; ensure downstream forks are notified.
+- **Verify carefully.** Make sure the redacted value is truly benign (example: test data, dummy keys, or hashed values).
+- **Mask the pattern going forward.** Add an `allowlist` entry in your repository-level `.gitleaks.toml` and commit that change with a note explaining the rationale.
+- **Re-run locally.** Validate that `gitleaks detect --redact` reports no findings after the allowlist entry is added.
+- **Reply on the PR.** Note that the finding is a false positive and link to the configuration change.
 
-## 4. Communicate
+## Need Help?
 
-- Document the remediation steps in the pull request or issue, noting credential rotation status.
-- For high-risk disclosures, email `civictechwr@gmail.com` to escalate privately.
-
-## 5. Verify and Prevent Recurrence
-
-- Re-run the Gitleaks workflow (or trigger it manually) to confirm the repository is clean.
-- Update the Gitleaks configuration in `.github/workflows/gitleaks.yml` to add new allowlist patterns, and only after validating they are false positives.
+- Mention `@CivicTechWR/organizers` in the pull request comment if you need support rotating credentials or cleaning history.
 
 ## Reference