Merge branch 'v3' into security/path-traversal-v3

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: {}

CHANGELOG.md

@@ -2,6 +2,65 @@
 
 <!-- version list -->
 
+## v3.12.1 (2026-05-11)
+
+### Bug Fixes
+
+- Add cross-platform install docs and conventional-pr make target
+  ([#2202](https://github.com/oscal-compass/compliance-trestle/pull/2202),
+  [`4444dc2`](https://github.com/oscal-compass/compliance-trestle/commit/4444dc29c1598b4096d74129f1c740757905d999))
+
+- Address PR review comments on multi-train release support
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Apply mdformat to maintenance_releases.md
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Convert negative security checks to positive allowlists
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Correct act install SHA to commit SHA (not tag object SHA)
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Pin act install to v0.2.87 and fix mdformat table padding
+  ([#2202](https://github.com/oscal-compass/compliance-trestle/pull/2202),
+  [`4444dc2`](https://github.com/oscal-compass/compliance-trestle/commit/4444dc29c1598b4096d74129f1c740757905d999))
+
+- Pre-configure act image to avoid interactive prompt in CI
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Upgrade cryptography to 46.0.7 (SNYK-PYTHON-CRYPTOGRAPHY-15809188,
+  SNYK-PYTHON-CRYPTOGRAPHY-15953315)
+  ([`e14ffd0`](https://github.com/oscal-compass/compliance-trestle/commit/e14ffd023bfa2f2dc91bf79827a999762d45690f))
+
+### Continuous Integration
+
+- Add act-based local workflow testing
+  ([#2202](https://github.com/oscal-compass/compliance-trestle/pull/2202),
+  [`4444dc2`](https://github.com/oscal-compass/compliance-trestle/commit/4444dc29c1598b4096d74129f1c740757905d999))
+
+- Add act-based local workflow testing and CI validation
+  ([#2202](https://github.com/oscal-compass/compliance-trestle/pull/2202),
+  [`4444dc2`](https://github.com/oscal-compass/compliance-trestle/commit/4444dc29c1598b4096d74129f1c740757905d999))
+
+- Add multi-train release support for maintenance branches
+  ([#2201](https://github.com/oscal-compass/compliance-trestle/pull/2201),
+  [`47ecd1d`](https://github.com/oscal-compass/compliance-trestle/commit/47ecd1d9a8bea3801dca4b2b6b89ef0cf39175e2))
+
+- Add Snyk exception for paramiko cryptographic algorithm issue
+  ([#2218](https://github.com/oscal-compass/compliance-trestle/pull/2218),
+  [`b4c9d94`](https://github.com/oscal-compass/compliance-trestle/commit/b4c9d94cfead66176ea475c39b20925b4340398b))
+
+- Fix merge commit validation and document release environment setup
+  ([#2218](https://github.com/oscal-compass/compliance-trestle/pull/2218),
+  [`b4c9d94`](https://github.com/oscal-compass/compliance-trestle/commit/b4c9d94cfead66176ea475c39b20925b4340398b))
+
+
 ## v3.12.0 (2026-02-13)
 
 ### Bug Fixes

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
 

trestle/__init__.py

@@ -23,4 +23,4 @@
 opinionated approach to OSCAL adoption.
 """
 
-__version__ = '3.12.0'
+__version__ = '3.12.1'