Merge pull request #2220 from oscal-compass/ci/cherry-pick-merge-commit-fix-v3

ci: fix merge commit validation and document release environment setup

Author: butler54

.github/workflows/python-push.yml

@@ -202,7 +202,7 @@ jobs:
           echo "No tag found; scanning commits since merge-base with main ($LAST_TAG)"
         fi
         ALLOWED_TYPES='^(fix|perf|chore|ci|docs|build|refactor|style|test|revert)(\(.*\))?:'
-        BAD_COMMITS=$(git log "$LAST_TAG"..HEAD --format='%s' | grep -iEvx "$ALLOWED_TYPES.*" || true)
+        BAD_COMMITS=$(git log "$LAST_TAG"..HEAD --no-merges --format='%s' | grep -iEvx "$ALLOWED_TYPES.*" || true)
         if [ -n "$BAD_COMMITS" ]; then
           echo "::error::All commits on maintenance branches must use an allowed type: fix, perf, chore, ci, docs, build, refactor, style, test, revert."
           echo "::error::The following commits do not match:"

.snyk

@@ -24,4 +24,13 @@ ignore:
           is temporary to allow pipeline progress.
         expires: 2026-03-28T00:00:00.000Z
         created: 2026-01-28T00:00:00.000Z
+  'SNYK-PYTHON-PARAMIKO-16425764':
+    - '*':
+        reason: >
+          Low severity cryptographic algorithm issue in paramiko@4.0.0.
+          No upgrade or patch available. Paramiko is used for remote
+          SSH operations which are not part of trestle's primary use case.
+          Accepted risk pending upstream fix.
+        expires: 2026-08-07T00:00:00.000Z
+        created: 2026-05-07T00:00:00.000Z
 patch: {}

docs/contributing/github_actions_setup.md

@@ -27,5 +27,35 @@ Pypi authorization must be setup following the procedure in the following docume
 Trestle supports releasing patches from maintenance branches (e.g., `v3`, `v4`). When creating a new maintenance branch, the following GitHub configuration is required:
 
 - **Branch protection**: Create a ruleset for `v[0-9]*` branches requiring PR reviews, status checks, squash merges, and restricted push access. See [Maintenance releases](maintenance_releases.md) for details.
-- **Release environment**: The `release` environment's deployment branch rules must include maintenance branches (add `v*` pattern or list branches explicitly).
+- **Release environment**: Add the specific maintenance branch to the `release` environment's deployment branch rules. See [Adding a branch to the release environment](#adding-a-branch-to-the-release-environment) below.
 - **PyPI trusted publisher**: Verify the trusted publisher configuration does not restrict publishing to `main` only.
+
+### Adding a branch to the release environment
+
+When cutting a new major version (e.g., v5.0.0), add the previous major version's maintenance branch (e.g., `v4`) to the `release` GitHub Environment. Each branch must be added **individually by exact name** (not using wildcards) to require deliberate opt-in for new maintenance branches.
+
+#### Using the GitHub UI
+
+1. Navigate to **Settings** → **Environments** → **release**
+1. Under **Deployment branches and tags**, click **Add deployment branch or tag rule**
+1. Select **Branch** as the rule type
+1. Enter the exact branch name: `v4` (not `v*` or `v[0-9]*`)
+1. Click **Add rule**
+
+#### Using the GitHub CLI
+
+```bash
+gh api repos/oscal-compass/compliance-trestle/environments/release/deployment-branch-policies \
+  --method POST -f name='v4' -f type='branch'
+```
+
+#### Verifying the configuration
+
+List all deployment branches to confirm the new branch was added:
+
+```bash
+gh api repos/oscal-compass/compliance-trestle/environments/release/deployment-branch-policies \
+  --jq '.branch_policies[] | {name, type}'
+```
+
+Expected output should include entries for `main` and all active maintenance branches (e.g., `v3`, `v4`).

docs/contributing/maintenance_releases.md

@@ -91,7 +91,7 @@ When a new major version is released (e.g., v5.0.0), create a maintenance branch
    - Restrict push access to maintainers
    - Disallow force pushes and deletions
 
-1. **Update the GitHub `release` environment** if it uses an explicit branch list (add the new branch)
+1. **Add the new branch to the `release` environment** — each maintenance branch must be explicitly allowed for deployments. Follow the step-by-step instructions in [GitHub actions setup → Adding a branch to the release environment](github_actions_setup.md#adding-a-branch-to-the-release-environment).
 
 1. **Consider enabling Dependabot** for security updates on the new maintenance branch