ci: fix merge commit validation and document release environment setup (#2218)

* ci: fix merge commit validation and document release environment setup

This commit addresses two maintenance branch release process issues:

1. The commit type validation step now excludes merge commits by adding
   `--no-merges` to the git log command. GitHub's auto-generated merge
   commit messages (e.g. "Merge pull request #NNN") don't follow
   conventional commit format, but semantic-release already ignores
   them (default_bump_level = 0), so validating them is unnecessary
   and causes false failures.

2. Expanded documentation in github_actions_setup.md with explicit
   step-by-step instructions for adding maintenance branches to the
   release environment, emphasizing individual branch names over
   wildcards to require deliberate opt-in. Updated maintenance_releases.md
   to cross-reference the detailed instructions.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Chris Butler <chris.butler@redhat.com>

* ci: add Snyk exception for paramiko cryptographic algorithm issue

Add exception for SNYK-PYTHON-PARAMIKO-16425764, a low severity
cryptographic algorithm vulnerability in paramiko@4.0.0. No upgrade
or patch is currently available. Paramiko is used for remote SSH
operations which are not part of trestle's primary use case.

The exception expires in 3 months to prompt re-evaluation when
upstream fixes become available.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Chris Butler <chris.butler@redhat.com>

---------

Signed-off-by: Chris Butler <chris.butler@redhat.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: butler54

.github/workflows/python-push.yml

@@ -255,7 +255,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