diff --git a/.changes/unreleased/release-workflows.yaml b/.changes/unreleased/release-workflows.yaml new file mode 100644 index 000000000..57f29d6a7 --- /dev/null +++ b/.changes/unreleased/release-workflows.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: Verify release metadata and milestones, check security findings, support phased signed-tag enforcement, and use pinned workflow actions and changelog-derived release notes. +time: 2026-11-17T00:00:01Z diff --git a/.github/dependabot.yml b/.github/dependabot.yml index e2922be11..8c8403581 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -3,6 +3,10 @@ version: 2 updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" - package-ecosystem: "gradle" directory: "/" schedule: diff --git a/.github/signing-maintainers b/.github/signing-maintainers new file mode 100644 index 000000000..36f20bf45 --- /dev/null +++ b/.github/signing-maintainers @@ -0,0 +1,4 @@ +# Intended release-tag signers. Public keys are resolved from each GitHub profile at check time. +goanpeca +ffumero2003 +sophiecarreras diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index a012f3be0..c32aa6aea 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -5,7 +5,6 @@ name: Changelog on: pull_request: - branches: [master, api-v2, 7.x] push: branches: [master] diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index a092aa6cb..3faded5c6 100644 --- a/.github/workflows/ci_cd.yml +++ b/.github/workflows/ci_cd.yml @@ -11,9 +11,12 @@ on: - api-v2 - 7.x # TODO: This is temporary and will be removed once we merge this branch to master branch +permissions: + contents: read + env: - OUTPUT_DIR: $GITHUB_WORKSPACE/build/outputs - OUTPUT_ZIP: b2-sdk-build-${GITHUB_RUN_NUMBER}.zip + OUTPUT_DIR: ${{ github.workspace }}/build/outputs + OUTPUT_ZIP: b2-sdk-build-${{ github.run_number }}.zip BUILD_NUMBER: ${{ github.run_number }} # These are stored in Bitwarden B2_ACCOUNT_ID: ${{ secrets.B2_ACCOUNT_ID }} @@ -25,22 +28,23 @@ jobs: runs-on: ${{ github.repository == 'Backblaze/b2-sdk-java-private' && 'self-hosted'|| 'ubuntu-latest' }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: fetch-depth: 0 + persist-credentials: false - - uses: actions/setup-java@v4 + - uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4 with: distribution: temurin java-version: '11' - - uses: gradle/actions/wrapper-validation@v4 + - uses: gradle/actions/wrapper-validation@ed408507eac070d1f99cc633dbcf757c94c7933a # v4 - name: Setup Gradle - uses: gradle/actions/setup-gradle@v4 + uses: gradle/actions/setup-gradle@ed408507eac070d1f99cc633dbcf757c94c7933a # v4 # --- uv + Python 3.13, then create a venv in $RUNNER_TEMP --- - name: Set up uv - uses: astral-sh/setup-uv@v5 + uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5 with: enable-cache: false @@ -64,15 +68,22 @@ jobs: - name: Build the distribution run: | - $GITHUB_WORKSPACE/gradlew build - mkdir -p ${{ env.OUTPUT_DIR }} - cp -v */build/libs/b2-sdk-*.{jar,pom,module} ${{ env.OUTPUT_DIR }} - cd ${{ env.OUTPUT_DIR }} - zip -r $GITHUB_WORKSPACE/build/${{ env.OUTPUT_ZIP }} * + "$GITHUB_WORKSPACE/gradlew" build + mkdir -p "$OUTPUT_DIR" + cp -v ./*/build/libs/b2-sdk-*.{jar,pom,module} "$OUTPUT_DIR" + cd "$OUTPUT_DIR" + zip -r "$GITHUB_WORKSPACE/build/$OUTPUT_ZIP" ./* + + - name: Validate publication task graph + env: + RELEASE_BUILD: true + run: | + ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository createBundle \ + --dry-run --no-daemon -PsonatypeUsername=dry-run -PsonatypePassword=dry-run - name: Deploy to internal Maven repo if: (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/api-v2' || github.ref == 'refs/heads/7.x') && github.repository == 'Backblaze/b2-sdk-java-private' - run: $GITHUB_WORKSPACE/gradlew publishMavenPublicationToRemoteRepository + run: '"$GITHUB_WORKSPACE/gradlew" publishMavenPublicationToRemoteRepository' env: ORG_GRADLE_PROJECT_remoteUsername: ${{ secrets.ARTIFACTORY_USERNAME }} ORG_GRADLE_PROJECT_remotePassword: ${{ secrets.ARTIFACTORY_TOKEN }} @@ -80,7 +91,7 @@ jobs: - name: Deploy to GH packages if: (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/api-v2' || github.ref == 'refs/heads/7.x') && github.repository == 'Backblaze/b2-sdk-java-private' - run: $GITHUB_WORKSPACE/gradlew publishMavenPublicationToRemoteRepository + run: '"$GITHUB_WORKSPACE/gradlew" publishMavenPublicationToRemoteRepository' env: ORG_GRADLE_PROJECT_remoteUsername: ${{ secrets.PACKAGES_USERNAME }} ORG_GRADLE_PROJECT_remotePassword: ${{ secrets.PACKAGES_TOKEN }} @@ -92,17 +103,40 @@ jobs: export PATH="$UV_VENV/bin:$PATH" "$GITHUB_WORKSPACE/maybe_upload_build_results" "${{ env.OUTPUT_ZIP }}" - - name: Check GitHub Pages status - if: github.ref == 'refs/heads/master' - uses: crazy-max/ghaction-github-status@v4 + - name: Upload Javadoc artifact + if: >- + github.event_name == 'push' && github.repository == 'Backblaze/b2-sdk-java' && + contains(fromJSON('["refs/heads/master", "refs/heads/api-v2", "refs/heads/7.x"]'), github.ref) + uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 with: - pages_threshold: major_outage - - - name: Deploy Javadoc - if: (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/api-v2' || github.ref == 'refs/heads/7.x') && success() - uses: crazy-max/ghaction-github-pages@v3 + path: core/build/docs/javadoc + + deploy-pages: + needs: build + if: >- + github.event_name == 'push' && github.repository == 'Backblaze/b2-sdk-java' && + contains(fromJSON('["refs/heads/master", "refs/heads/api-v2", "refs/heads/7.x"]'), github.ref) + runs-on: ubuntu-latest + permissions: + contents: read + pages: write + id-token: write + concurrency: + group: github-pages + cancel-in-progress: false + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: - target_branch: gh-pages - build_dir: core/build/docs/javadoc - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + persist-credentials: false + - name: Check GitHub Pages status + shell: bash + run: | + set -euo pipefail + curl --fail --show-error --silent --location --max-time 30 \ + https://www.githubstatus.com/api/v2/components.json | python3 scripts/release.py pages-status + - name: Deploy Javadoc + id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index b064cf61e..19fb015ed 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -6,24 +6,80 @@ on: push: tags: ['v*'] +permissions: + contents: read + +concurrency: + group: maven-central-${{ github.ref }} + cancel-in-progress: false + jobs: + release-checks: + if: github.repository == 'Backblaze/b2-sdk-java' + runs-on: ubuntu-latest + permissions: + contents: read + security-events: read + issues: read + env: + RELEASE_TAG: ${{ github.ref_name }} + steps: + # Read the key registry and gate implementation from the reviewed default branch. + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + ref: master + fetch-depth: 0 + persist-credentials: false + - name: Verify release tag + env: + ENFORCE_SIGNED_TAGS: ${{ vars.ENFORCE_SIGNED_TAGS }} + GH_TOKEN: ${{ github.token }} + run: | + python3 scripts/release.py verify-commit "$RELEASE_TAG" "$GITHUB_SHA" + bash scripts/verify-release-tag.sh "$RELEASE_TAG" + - name: Check tag, version, and changelog agreement + run: | + git worktree add --detach "$RUNNER_TEMP/release-metadata" "$GITHUB_SHA" + python3 scripts/release.py --root "$RUNNER_TEMP/release-metadata" notes "$RELEASE_TAG" > /dev/null + - name: Require complete version milestone + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release.py milestone "$RELEASE_TAG" + - name: Require security clearance + env: + GH_TOKEN: ${{ secrets.RELEASE_READ_TOKEN }} + run: python3 scripts/release.py security + deploy: name: Deploy + needs: release-checks if: github.repository == 'Backblaze/b2-sdk-java' runs-on: ubuntu-latest + permissions: + contents: write + env: + RELEASE_TAG: ${{ github.ref_name }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: + ref: ${{ github.sha }} fetch-depth: 0 + persist-credentials: false - - uses: actions/setup-java@v4 + - uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4 with: distribution: 'temurin' java-version: '11' - - uses: gradle/actions/wrapper-validation@v4 + - uses: gradle/actions/wrapper-validation@ed408507eac070d1f99cc633dbcf757c94c7933a # v4 - name: Setup Gradle - uses: gradle/actions/setup-gradle@v4 + uses: gradle/actions/setup-gradle@ed408507eac070d1f99cc633dbcf757c94c7933a # v4 + + - name: Build and test the release + run: ./gradlew build --no-daemon + + - name: Extract release notes + run: python3 scripts/release.py notes "$RELEASE_TAG" > "$RUNNER_TEMP/release-notes.md" - name: Deploy to Maven Central run: ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository createBundle --no-daemon --stacktrace @@ -34,23 +90,15 @@ jobs: ORG_GRADLE_PROJECT_sonatypeUsername: ${{ secrets.SONATYPE_TOKEN_USERNAME }} ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.SONATYPE_TOKEN_PASSWORD }} - - name: Get tag name - id: get_tag - shell: bash - run: | - tag_name="$(echo $GITHUB_REF | cut -d / -f 3)" - echo ::set-output name=tag::$tag_name - - name: Create GitHub Release - uses: softprops/action-gh-release@v2 env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: ${{ steps.get_tag.outputs.tag }} - name: ${{ steps.get_tag.outputs.tag }} - prerelease: false - draft: false - files: | - core/build/libs/bundle-*.jar - httpclient/build/libs/bundle-*.jar - samples/build/libs/bundle-*.jar + GH_TOKEN: ${{ github.token }} + shell: bash + run: | + shopt -s nullglob + assets=(core/build/libs/bundle-*.jar httpclient/build/libs/bundle-*.jar samples/build/libs/bundle-*.jar) + [ "${#assets[@]}" -eq 3 ] || { echo 'Expected one release bundle for each module' >&2; exit 1; } + flags=(--latest) + if [[ "$RELEASE_TAG" == *-* ]]; then flags=(--prerelease); fi + gh release create "$RELEASE_TAG" --verify-tag --title "$RELEASE_TAG" \ + --notes-file "$RUNNER_TEMP/release-notes.md" "${flags[@]}" "${assets[@]}" diff --git a/RELEASE.md b/RELEASE.md index 1da08a295..6c5d29590 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -18,6 +18,39 @@ approach in [Blazer's release guide](https://github.com/Backblaze/blazer/blob/ma Do not run a publishing task locally as a verification step. A tag push starts the production deployment, including closing and releasing the Sonatype staging repository. +## Repository setup and signed-tag rollout + +The intended release maintainers are `goanpeca`, `ffumero2003`, and `sophiecarreras`, listed in +`.github/signing-maintainers`. The verifier resolves their public keys from +`https://github.com/.gpg`, `https://github.com/.keys`, and the paginated public +`users//ssh_signing_keys` API at check time and runs +`git verify-tag` with an isolated keyring and SSH allowed-signers file. GitHub profile key changes +therefore affect the next verification; review the username list through a PR. +SSH authorization uses the registered keys under a fixed signer principal. The tagger email is +descriptive metadata and is not used to construct the allowed-signers file. + +Tag verification is **warn-only by default**. Before enabling it, each intended signer must create a +GPG or SSH signing key and register the public key on their GitHub account. Confirm that their signed +tag passes verification, then run `gh variable set ENFORCE_SIGNED_TAGS --body true` for this repository. +Once enabled, an +unsigned, lightweight, unrecognized, or unverifiable tag blocks publication. In warn-only mode those +conditions produce a workflow warning; the security, milestone, and metadata gates still enforce. + +An administrator must complete the following before the workflow changes are used for a release: + +- Supply `RELEASE_READ_TOKEN`, a read-only token authorized for this repository's code-scanning, + Dependabot, secret-scanning alerts, repository security advisories (including drafts), and issues. + Enable these sources and grant access: a disabled or unreadable source holds publication. + The ordinary workflow token is used for checkout, signing-key API lookups, milestone reads, + and release creation, with explicit job permissions; Maven signing/publishing secrets are exposed + only to the publish step. +- Change Settings → Pages → Build and deployment → Source from **Deploy from a branch** to + **GitHub Actions**. Configure the `github-pages` environment to allow the documentation branches + `master`, `api-v2`, and `7.x`. The official Pages deployment uses GitHub OIDC with `pages: write` + and `id-token: write`; this does not change Maven Central authentication. +- Make `changelog-check` a required PR check and protect `.github/signing-maintainers` and the + release workflows through maintainer review. Keep Dependabot's GitHub Actions updates enabled. + ## Changelog and versioning Use semantic versioning: fixes use a patch release, compatible features a minor release, and @@ -64,6 +97,19 @@ workflow files and human-authored changes still need a fragment. including findings without a patched dependency. Failures to read findings are unverified, not clean. A maintainer must resolve or dismiss findings with a written reason before release. + ```bash + GH_TOKEN="$RELEASE_READ_TOKEN" python3 scripts/release.py security + # After the release-prep PR has merged, the milestone must contain no open issues or PRs: + python3 scripts/release.py milestone "$TAG" + ``` + + The gate reads all pages of GitHub code-scanning alerts on `master`, Dependabot alerts, + draft/triage repository advisories, secret-scanning alerts, and severity-labeled open issues. + Medium/high/critical findings block even without a patched version; all open secret alerts + and unscored active advisories or code-scanning alerts block. Low findings do not block. The gate prints counts, + never unpublished advisory text or secret values. Do not put private advisory details in + a public issue. API failures are not a waiver; restore access and rerun the gate. + 3. Batch the changelog and update the version in one operation: ```bash @@ -140,6 +186,15 @@ The tag-triggered deploy workflow publishes using the existing Gradle command: Maven Central, GPG artifact signing, the Sonatype staging endpoint, and the release/close tasks are unchanged by the changelog tooling. Never run this production command as a dry-run substitute. +Before publishing, `release-checks` reads its gate implementation and maintainer list from `master`, +requires the tag to resolve to the workflow's immutable event commit on `master`, checks +version/changelog agreement, verifies the tag in the configured mode, and requires security clearance +and a complete `vX.Y.Z` milestone. Metadata validation and the `deploy` checkout use that same event +commit. `deploy` depends on those checks and runs the Gradle build before publishing. After successful +publication it runs `gh release create` +with the exact `.changes/vX.Y.Z.md` section as `--notes-file` and the three existing module bundles. +No default or automatically generated release body is used. + ## Verify the published release 1. Inspect the deployment run for the tag and confirm the Sonatype close/release step succeeded: diff --git a/scripts/release.py b/scripts/release.py index 1f30bb0ce..d86894270 100644 --- a/scripts/release.py +++ b/scripts/release.py @@ -2,6 +2,7 @@ """Release metadata checks. Uses the standard library and the pinned Changie binary.""" import argparse +import json import os import pathlib import re @@ -83,6 +84,125 @@ def changelog_check(root, base, dependabot=False): print("changelog-check: generated changelog, fragments, and version agree") +def api_list(repo, resource): + if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repo): + raise ValueError("invalid repository name") + result = subprocess.run(["gh", "api", "--paginate", "--slurp", + "repos/" + repo + "/" + resource], capture_output=True, text=True) + if result.returncode: + raise ValueError("cannot verify " + resource.split("?")[0] + "; check security-read access") + try: + pages = json.loads(result.stdout) + if not isinstance(pages, list) or not all(isinstance(page, list) for page in pages): + raise ValueError() + items = [item for page in pages for item in page] + if not all(isinstance(item, dict) for item in items): + raise ValueError() + return items + except (ValueError, TypeError): + raise ValueError("cannot verify " + resource.split("?")[0] + ": invalid API response") from None + + +def blocks_release(severity): + if severity is None: + return True # An untriaged advisory cannot establish a clear release gate. + if severity not in ("low", "medium", "high", "critical"): + raise ValueError("cannot verify an unknown severity") + return severity != "low" + + +def security_gate(repo): + # Generic patterns require an explicit secret_type filter in GitHub's REST API. + generic_types = ("ec_private_key", "generic_private_key", "http_basic_authentication_header", + "http_bearer_authentication_header", "mongodb_connection_string", "mysql_connection_url", + "openssh_private_key", "pgp_private_key", "postgres_connection_string", "rsa_private_key", "password") + sources = ( + ("Code scanning", "code-scanning/alerts?state=open&ref=refs/heads/master&per_page=100"), + ("Dependabot", "dependabot/alerts?state=open&per_page=100"), + ("Secret scanning", "secret-scanning/alerts?state=open&per_page=100&hide_secret=true"), + ("Generic secret scanning", "secret-scanning/alerts?state=open&per_page=100&hide_secret=true&secret_type=" + + ",".join(generic_types)), + ("Repository advisories", "security-advisories?per_page=100"), + ("Issues", "issues?state=open&per_page=100"), + ) + blocked = False + allowed_states = { + "Code scanning": ("open", "fixed", "dismissed"), + "Dependabot": ("open", "fixed", "dismissed", "auto_dismissed"), + "Secret scanning": ("open", "resolved"), + "Generic secret scanning": ("open", "resolved"), + "Repository advisories": ("draft", "triage", "published", "closed", "withdrawn"), + "Issues": ("open", "closed"), + } + for name, endpoint in sources: + count = 0 + try: + for item in api_list(repo, endpoint): + state = item["state"] + if state not in allowed_states[name]: + raise ValueError("cannot verify " + name + ": unknown finding state") + if name == "Repository advisories": + count += state in ("draft", "triage") and blocks_release(item["severity"]) + elif state == "open": + if name == "Code scanning": + severity = item["rule"].get("security_severity_level") + count += blocks_release(severity) + elif name == "Dependabot": + count += blocks_release(item["security_advisory"]["severity"]) + elif name in ("Secret scanning", "Generic secret scanning"): + count += 1 + elif name == "Issues": + labels = [re.sub(r"[\s:/_-]+", "", label["name"].lower()) for label in item["labels"]] + count += any(label in ("medium", "high", "critical", "severitymedium", + "severityhigh", "severitycritical") for label in labels) + except (KeyError, TypeError, AttributeError): + raise ValueError("cannot verify " + name + ": incomplete API response") from None + print(name + (": HOLD (" + str(count) + " blocking finding(s))" if count else ": clear")) + blocked |= count > 0 + if blocked: + raise ValueError("security gate holds this release") + print("security gate: clear") + + +def milestone_gate(repo, tag): + if not re.fullmatch("v" + VERSION, tag): + raise ValueError("expected a version tag") + matches = [item for item in api_list(repo, "milestones?state=all&per_page=100") if item.get("title") == tag] + if len(matches) != 1 or matches[0].get("open_issues") != 0: + raise ValueError("milestone " + tag + " must exist and have no open issues or pull requests") + print("milestone gate: clear (" + tag + ")") + + +def verify_commit(root, tag, expected): + if not re.fullmatch("v" + VERSION, tag) or not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", expected): + raise ValueError("expected a version tag and immutable event commit") + actual = subprocess.check_output( + ["git", "rev-parse", "--verify", "refs/tags/" + tag + "^{commit}"], cwd=root, text=True + ).strip() + if actual != expected: + raise ValueError("release tag no longer matches the event commit") + result = subprocess.run(["git", "merge-base", "--is-ancestor", expected, "origin/master"], cwd=root) + if result.returncode: + raise ValueError("release event commit is not on origin/master") + print("release commit: matches event and origin/master") + + +def pages_status(): + try: + components = json.load(sys.stdin)["components"] + pages = [item for item in components if item["name"] in ("Pages", "GitHub Pages")] + if len(pages) != 1: + raise ValueError() + status = pages[0]["status"] + except (ValueError, KeyError, TypeError): + raise ValueError("cannot verify GitHub Pages status") from None + if status == "major_outage": + raise ValueError("GitHub Pages has a major outage; hold Javadoc deployment") + if status not in ("operational", "degraded_performance", "partial_outage", "under_maintenance"): + raise ValueError("cannot verify GitHub Pages status") + print("GitHub Pages status: " + status) + + def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--root", type=pathlib.Path, default=pathlib.Path(__file__).resolve().parents[1]) @@ -92,12 +212,29 @@ def main(): changelog = commands.add_parser("changelog-check") changelog.add_argument("--base") changelog.add_argument("--dependabot", action="store_true") + security = commands.add_parser("security") + security.add_argument("--repo", default="Backblaze/b2-sdk-java") + milestone = commands.add_parser("milestone") + milestone.add_argument("tag") + milestone.add_argument("--repo", default="Backblaze/b2-sdk-java") + commands.add_parser("pages-status") + commit = commands.add_parser("verify-commit") + commit.add_argument("tag") + commit.add_argument("sha") args = parser.parse_args() try: if args.command == "notes": print(release_notes(args.root, args.tag), end="") elif args.command == "changelog-check": changelog_check(args.root, args.base, args.dependabot) + elif args.command == "security": + security_gate(args.repo) + elif args.command == "milestone": + milestone_gate(args.repo, args.tag) + elif args.command == "pages-status": + pages_status() + elif args.command == "verify-commit": + verify_commit(args.root, args.tag, args.sha) except (ValueError, OSError, subprocess.CalledProcessError) as error: print("HOLD: " + str(error), file=sys.stderr) return 1 diff --git a/scripts/tests/test_release_gates.py b/scripts/tests/test_release_gates.py new file mode 100644 index 000000000..7f3394e9b --- /dev/null +++ b/scripts/tests/test_release_gates.py @@ -0,0 +1,116 @@ +"""Exercise API decisions using paginated fixtures; never contact GitHub.""" + +import json +import os +import pathlib +import subprocess +import sys +import tempfile +import unittest + + +SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "release.py" +SOURCES = ("code-scanning/alerts", "dependabot/alerts", "secret-scanning/alerts", "security-advisories", "issues") + + +class ReleaseGateTest(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = pathlib.Path(self.temporary.name) + fake = self.root / "gh" + fake.write_text("""#!/usr/bin/env python3 +import json, os, sys +if '--paginate' not in sys.argv or '--slurp' not in sys.argv: + sys.exit(90) +endpoint = next(arg for arg in sys.argv if arg.startswith('repos/')).split('?')[0].split('repos/example/sdk/')[1] +fixture = json.loads(os.environ['RELEASE_GATE_FIXTURE']) +value = fixture.get(endpoint, 'unreadable') +if value == 'unreadable': + sys.exit(1) +print(json.dumps(value)) +""") + fake.chmod(0o755) + self.data = {source: [[]] for source in SOURCES} + self.data["milestones"] = [[{"title": "v1.2.3", "number": 4, "open_issues": 0}]] + + def run_gate(self, command="security", *arguments): + environment = dict(os.environ, PATH=str(self.root) + os.pathsep + os.environ["PATH"], + RELEASE_GATE_FIXTURE=json.dumps(self.data), GH_TOKEN="test-only") + return subprocess.run([sys.executable, str(SCRIPT), command, *arguments, "--repo", "example/sdk"], + env=environment, text=True, capture_output=True) + + def test_all_readable_empty_sources_pass(self): + result = self.run_gate() + self.assertEqual(0, result.returncode, result.stderr) + self.assertIn("security gate: clear", result.stdout) + + def test_medium_high_and_critical_dependencies_block_even_without_patch(self): + for severity in ("medium", "high", "critical"): + with self.subTest(severity=severity): + self.data["dependabot/alerts"] = [[], [{"state": "open", "security_advisory": {"severity": severity}}]] + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertIn("Dependabot", result.stdout) + + def test_open_code_scanning_and_severity_labeled_issues_block(self): + self.data["code-scanning/alerts"] = [[{"state": "open", "rule": {"security_severity_level": "high"}}]] + self.data["issues"] = [[{"state": "open", "labels": [{"name": "severity: medium"}]}]] + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertIn("Code scanning: HOLD", result.stdout) + self.assertIn("Issues: HOLD", result.stdout) + + def test_low_or_closed_findings_do_not_block(self): + self.data["dependabot/alerts"] = [[ + {"state": "open", "security_advisory": {"severity": "low"}}, + {"state": "dismissed", "security_advisory": {"severity": "critical"}}, + ]] + result = self.run_gate() + self.assertEqual(0, result.returncode, result.stderr) + + def test_unreadable_or_malformed_security_response_blocks(self): + for value in ("unreadable", {"message": "not an alerts list"}): + with self.subTest(value=value): + self.data["code-scanning/alerts"] = value + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertIn("cannot verify", result.stderr) + + def test_draft_advisory_and_secret_alerts_block_without_disclosing_contents(self): + self.data["security-advisories"] = [[{"state": "draft", "severity": "medium", "summary": "PRIVATE"}]] + self.data["secret-scanning/alerts"] = [[{"state": "open", "secret": "PRIVATE"}]] + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertNotIn("PRIVATE", result.stdout + result.stderr) + + def test_unscored_active_advisory_blocks(self): + self.data["security-advisories"] = [[{"state": "triage", "severity": None}]] + self.assertNotEqual(0, self.run_gate().returncode) + + def test_unscored_code_scanning_alert_blocks(self): + self.data["code-scanning/alerts"] = [[{"state": "open", "rule": {"id": "unscored-fixture"}}]] + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertIn("Code scanning: HOLD", result.stdout) + + def test_unknown_finding_state_is_not_clean(self): + self.data["dependabot/alerts"] = [[{"state": "unexpected", "security_advisory": {"severity": "high"}}]] + result = self.run_gate() + self.assertNotEqual(0, result.returncode) + self.assertIn("cannot verify", result.stderr) + + def test_complete_version_milestone_passes(self): + result = self.run_gate("milestone", "v1.2.3") + self.assertEqual(0, result.returncode, result.stderr) + self.assertIn("milestone gate: clear", result.stdout) + + def test_missing_milestone_or_open_work_blocks(self): + self.data["milestones"] = [[]] + self.assertNotEqual(0, self.run_gate("milestone", "v1.2.3").returncode) + self.data["milestones"] = [[{"title": "v1.2.3", "number": 4, "open_issues": 1}]] + self.assertNotEqual(0, self.run_gate("milestone", "v1.2.3").returncode) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_release_secret_patterns.py b/scripts/tests/test_release_secret_patterns.py new file mode 100644 index 000000000..a808ab231 --- /dev/null +++ b/scripts/tests/test_release_secret_patterns.py @@ -0,0 +1,96 @@ +"""Check provider and generic alert queries against the documented API contract.""" + +import json +import os +import pathlib +import subprocess +import sys +import tempfile +import unittest +from urllib.parse import parse_qs + + +SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "release.py" +GENERIC_TYPES = ("ec_private_key", "generic_private_key", "http_basic_authentication_header", + "http_bearer_authentication_header", "mongodb_connection_string", "mysql_connection_url", + "openssh_private_key", "pgp_private_key", "postgres_connection_string", "rsa_private_key", "password") + + +class SecretPatternGateTest(unittest.TestCase): + def setUp(self): + temporary = tempfile.TemporaryDirectory(prefix="b2-secret-query-") + self.addCleanup(temporary.cleanup) + self.root = pathlib.Path(temporary.name) + self.log = self.root / "requests.jsonl" + gh = self.root / "gh" + gh.write_text("#!" + sys.executable + "\n" + ''' +import json, os, sys +from urllib.parse import parse_qs +if '--paginate' not in sys.argv or '--slurp' not in sys.argv: + sys.exit(90) +request = next(arg for arg in sys.argv if arg.startswith('repos/example/sdk/')) +resource, _, query = request.partition('?') +parameters = parse_qs(query) +with open(os.environ['SECRET_QUERY_LOG'], 'a') as output: + output.write(json.dumps(request) + '\\n') +pages = [[]] +if resource.endswith('/secret-scanning/alerts'): + target = os.environ['SECRET_QUERY_TYPE'] + generic = 'secret_type' in parameters + selected = parameters.get('secret_type', [''])[0].split(',') + matches = (generic and target in selected) or (not generic and not target) + mode = os.environ['SECRET_QUERY_MODE'] + if generic and mode == 'unreadable': + sys.exit(1) + if generic and mode == 'malformed': + print(json.dumps({'message': 'not an alert list'})) + sys.exit(0) + if matches and mode != 'empty': + pages = [[], [{'state': 'open', 'secret_type': target or 'example_provider', 'secret': 'DO-NOT-PRINT'}]] +print(json.dumps(pages)) +''') + gh.chmod(0o755) + + def run_gate(self, secret_type="rsa_private_key", mode="open"): + self.log.write_text("") + environment = dict(os.environ, PATH=str(self.root) + os.pathsep + os.environ["PATH"], GH_TOKEN="test-only", + SECRET_QUERY_LOG=str(self.log), SECRET_QUERY_TYPE=secret_type, SECRET_QUERY_MODE=mode) + result = subprocess.run([sys.executable, str(SCRIPT), "security", "--repo", "example/sdk"], + env=environment, capture_output=True, text=True) + requests = [json.loads(line) for line in self.log.read_text().splitlines()] + return result, requests + + def test_each_generic_pattern_blocks_without_disclosing_values(self): + for secret_type in GENERIC_TYPES: + with self.subTest(secret_type=secret_type): + result, requests = self.run_gate(secret_type) + self.assertNotEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("Generic secret scanning: HOLD", result.stdout) + self.assertNotIn("DO-NOT-PRINT", result.stdout + result.stderr) + self.assertTrue(any(secret_type in parse_qs(request.partition('?')[2]).get('secret_type', [''])[0].split(',') + for request in requests), requests) + + def test_unreadable_or_malformed_generic_alerts_hold_the_release(self): + for mode in ("unreadable", "malformed"): + with self.subTest(mode=mode): + result, _ = self.run_gate(mode=mode) + self.assertNotEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("cannot verify", result.stderr) + + def test_provider_alerts_remain_blocking(self): + result, _ = self.run_gate(secret_type="") + self.assertNotEqual(0, result.returncode) + self.assertIn("Secret scanning: HOLD", result.stdout) + self.assertNotIn("DO-NOT-PRINT", result.stdout + result.stderr) + + def test_empty_queries_pass_and_request_hidden_secret_values(self): + result, requests = self.run_gate(mode="empty") + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + parameters = [parse_qs(request.partition('?')[2]) for request in requests if '/secret-scanning/alerts?' in request] + self.assertTrue(any('secret_type' in item for item in parameters), requests) + self.assertTrue(any('secret_type' not in item for item in parameters), requests) + self.assertTrue(all(item.get('hide_secret') == ['true'] for item in parameters), requests) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_signed_tags.py b/scripts/tests/test_signed_tags.py new file mode 100644 index 000000000..77199301b --- /dev/null +++ b/scripts/tests/test_signed_tags.py @@ -0,0 +1,276 @@ +"""Verify real disposable Git/GPG/SSH signatures; mock only the key-download boundary.""" + +import base64 +import os +import pathlib +import shutil +import struct +import subprocess +import tempfile +import unittest + + +SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "verify-release-tag.sh" +REGISTRY = SCRIPT.parents[1] / ".github/signing-maintainers" + + +class SignedTagTest(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.temporary = tempfile.TemporaryDirectory(prefix="b2-tag-", dir="/tmp") + cls.root = pathlib.Path(cls.temporary.name) + cls.home = cls.root / "gnupg" + cls.home.mkdir(mode=0o700) + cls.environment = dict(os.environ, GNUPGHOME=str(cls.home), GIT_CONFIG_GLOBAL=os.devnull, + GIT_CONFIG_NOSYSTEM="1") + cls.repo = cls.root / "repo" + cls.repo.mkdir() + cls.call(["git", "init", "-q"]) + cls.call(["git", "config", "user.name", "Release Fixture"]) + cls.call(["git", "config", "user.email", "fixture@example.invalid"]) + cls.call(["git", "-c", "commit.gpgSign=false", "commit", "--allow-empty", "-qm", "Fixture"]) + cls.reviewed = cls.call(["git", "rev-parse", "HEAD"]).stdout.strip() + cls.call(["git", "update-ref", "refs/remotes/origin/master", cls.reviewed]) + cls.call(["gpg", "--batch", "--pinentry-mode", "loopback", "--passphrase", "", + "--quick-generate-key", "Release Fixture ", "ed25519", "sign", "0"]) + keys = cls.call(["gpg", "--with-colons", "--list-secret-keys"]).stdout + fingerprint = next(line.split(":")[9] for line in keys.splitlines() if line.startswith("fpr:")) + cls.public_gpg = cls.root / "fixture.gpg" + cls.public_gpg.write_text(cls.call(["gpg", "--armor", "--export", fingerprint]).stdout) + cls.call(["git", "-c", "gpg.format=openpgp", "-c", "user.signingkey=" + fingerprint, + "tag", "-s", "v1.2.3", "-m", "v1.2.3"]) + cls.call(["git", "tag", "v1.2.4"]) + cls.ssh_key = cls.root / "ssh-key" + cls.call(["ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-f", str(cls.ssh_key)]) + cls.call(["git", "-c", "gpg.format=ssh", "-c", "user.signingkey=" + str(cls.ssh_key), + "tag", "-s", "v1.2.5", "-m", "v1.2.5"]) + cls.call(["git", "-c", "commit.gpgSign=false", "commit", "--allow-empty", "-qm", "Unreviewed fixture"]) + cls.unreviewed = cls.call(["git", "rev-parse", "HEAD"]).stdout.strip() + cls.call(["git", "tag", "v1.2.8"]) + cls.maintainers = cls.root / "maintainers" + cls.maintainers.write_text("fixture-maintainer\n") + cls.bin = cls.root / "bin" + cls.bin.mkdir() + curl = cls.bin / "curl" + curl.write_text("""#!/usr/bin/env python3 +import os, pathlib, sys +if os.environ.get('FIXTURE_KEY_REQUESTS'): + with open(os.environ['FIXTURE_KEY_REQUESTS'], 'a') as output: + output.write(sys.argv[-1] + '\\n') +path = os.environ.get('FIXTURE_GPG' if sys.argv[-1].endswith('.gpg') else 'FIXTURE_SSH') +if path: + print(pathlib.Path(path).read_text(), end='') +""") + curl.chmod(0o755) + gh = cls.bin / "gh" + gh.write_text("""#!/usr/bin/env python3 +import os, pathlib, sys +if os.environ.get('FIXTURE_KEY_REQUESTS'): + with open(os.environ['FIXTURE_KEY_REQUESTS'], 'a') as output: + output.write(sys.argv[3] + '\\n') +path = os.environ.get('FIXTURE_SSH_SIGNING') +if path: + print(pathlib.Path(path).read_text(), end='') +""") + gh.chmod(0o755) + + @classmethod + def call(cls, command): + result = subprocess.run(command, cwd=cls.repo, env=cls.environment, text=True, capture_output=True) + if result.returncode: + raise RuntimeError(str(command) + ": " + result.stderr) + return result + + @classmethod + def tearDownClass(cls): + subprocess.run(["gpgconf", "--kill", "all"], env=cls.environment, capture_output=True) + cls.temporary.cleanup() + + def verify(self, tag="v1.2.3", enforce="true", registered=True, signing_only=False): + environment = dict(self.environment, PATH=str(self.bin) + os.pathsep + self.environment["PATH"], + ENFORCE_SIGNED_TAGS=enforce, + FIXTURE_GPG=str(self.public_gpg) if registered else "", + FIXTURE_SSH=str(self.ssh_key) + ".pub" if registered else "", + FIXTURE_SSH_SIGNING=str(self.ssh_key) + ".pub" if signing_only else "") + return subprocess.run(["bash", str(SCRIPT), tag, str(self.maintainers)], + cwd=self.repo, env=environment, text=True, capture_output=True) + + def test_registered_gpg_signature_passes_enforcing_gate(self): + result = self.verify() + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("verified", result.stdout) + + def test_default_maintainer_registry_is_consumed(self): + maintainers = ("goanpeca", "ffumero2003", "sophiecarreras") + registered = [line.strip() for line in REGISTRY.read_text().splitlines() + if line.strip() and not line.lstrip().startswith("#")] + self.assertCountEqual(maintainers, registered) + default = self.repo / ".github/signing-maintainers" + default.parent.mkdir(exist_ok=True) + shutil.copyfile(REGISTRY, default) + requests = self.root / "default-maintainer-requests.log" + environment = dict(self.environment, PATH=str(self.bin) + os.pathsep + self.environment["PATH"], + ENFORCE_SIGNED_TAGS="true", FIXTURE_GPG=str(self.public_gpg), + FIXTURE_SSH="", FIXTURE_SSH_SIGNING="", FIXTURE_KEY_REQUESTS=str(requests)) + result = subprocess.run(["bash", str(SCRIPT), "v1.2.3"], cwd=self.repo, + env=environment, text=True, capture_output=True) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + expected = [] + for username in maintainers: + expected.extend(("https://github.com/" + username + ".gpg", + "https://github.com/" + username + ".keys", + "users/" + username + "/ssh_signing_keys?per_page=100")) + self.assertCountEqual(expected, requests.read_text().splitlines()) + + def test_registered_ssh_signature_passes_enforcing_gate(self): + tag = self.call(["git", "cat-file", "tag", "v1.2.5"]).stdout + self.assertIn("tagger Release Fixture ", tag) + result = self.verify("v1.2.5") + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("verified", result.stdout) + + def test_ssh_verification_uses_a_fixed_registered_key_principal(self): + trace = self.root / "ssh-principal.trace" + self.environment = dict(self.environment, GIT_TRACE=str(trace)) + result = self.verify("v1.2.5") + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertRegex(trace.read_text(), r"ssh-keygen -Y verify[^\n]* -I release-maintainer(?: |$)") + + def test_registered_ssh_key_accepts_valid_tagger_email_punctuation(self): + for index, email in enumerate(("o'hara@example.org", "fixture+release@example.invalid")): + with self.subTest(email=email): + tag = "v1.2." + str(30 + index) + self.make_ssh_tag(tag, email, self.ssh_key) + result = self.verify(tag) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("verified", result.stdout) + + def make_ssh_tag(self, name, email, key): + content = ("object " + self.reviewed + "\ntype commit\ntag " + name + "\n" + "tagger Release Fixture <" + email + "> 1700000000 +0000\n\n" + name + "\n") + unsigned = self.root / (name + ".txt") + unsigned.write_text(content) + self.call(["ssh-keygen", "-Y", "sign", "-f", str(key), "-n", "git", str(unsigned)]) + signed = content + unsigned.with_suffix(".txt.sig").read_text() + result = subprocess.run(["git", "hash-object", "-t", "tag", "-w", "--stdin"], + cwd=self.repo, env=self.environment, input=signed, + text=True, capture_output=True) + self.assertEqual(0, result.returncode, result.stderr) + self.call(["git", "update-ref", "refs/tags/" + name, result.stdout.strip()]) + + def test_ssh_tagger_email_cannot_add_an_unregistered_key(self): + key = self.root / "other-ssh-key" + self.call(["ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-f", str(key)]) + public = " ".join(key.with_suffix(".pub").read_text().split()[:2]) + self.make_ssh_tag("v1.2.10", 'fixture namespaces="git" ' + public, key) + result = self.verify("v1.2.10") + self.assertNotEqual(0, result.returncode, result.stdout) + self.assertIn("not verified", result.stderr) + + def test_signed_tagger_text_cannot_change_the_registered_key_principal(self): + for index, email in enumerate(("fixture,*@example.invalid", "fixture?@example.invalid")): + with self.subTest(email=email): + tag = "v1.2." + str(20 + index) + self.make_ssh_tag(tag, email, self.ssh_key) + trace = self.root / (tag + ".trace") + self.environment = dict(self.environment, GIT_TRACE=str(trace)) + result = self.verify(tag) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertRegex(trace.read_text(), r"ssh-keygen -Y verify[^\n]* -I release-maintainer(?: |$)") + + def test_ssh_key_registered_only_for_signing_passes(self): + result = self.verify("v1.2.5", registered=False, signing_only=True) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn("verified", result.stdout) + + def test_registered_security_key_types_reach_allowed_signers(self): + def fields(public_key): + blob = base64.b64decode(public_key.read_text().split()[1]) + result = [] + while blob: + length = struct.unpack(">I", blob[:4])[0] + result.append(blob[4:4 + length]) + blob = blob[4 + length:] + return result + + def public_line(key_type, *parts): + values = (key_type.encode(),) + parts + (b"ssh:",) + blob = b"".join(struct.pack(">I", len(value)) + value for value in values) + return key_type + " " + base64.b64encode(blob).decode() + " fixture" + + ecdsa = self.root / "security-key-ecdsa-fixture" + self.call(["ssh-keygen", "-q", "-t", "ecdsa", "-b", "256", "-N", "", "-f", str(ecdsa)]) + ed25519_fields = fields(self.ssh_key.with_suffix(".pub")) + ecdsa_fields = fields(ecdsa.with_suffix(".pub")) + keys = (public_line("sk-ssh-ed25519@openssh.com", ed25519_fields[1]), + public_line("sk-ecdsa-sha2-nistp256@openssh.com", *ecdsa_fields[1:])) + capture_bin = self.root / "capture-bin" + capture_bin.mkdir() + capture = self.root / "allowed-signers.capture" + real_git = shutil.which("git", path=self.environment["PATH"]) + git = capture_bin / "git" + git.write_text("""#!/usr/bin/env python3 +import os, pathlib, shutil, subprocess, sys +for argument in sys.argv[1:]: + if argument.startswith('gpg.ssh.allowedSignersFile='): + shutil.copyfile(argument.partition('=')[2], os.environ['FIXTURE_ALLOWED_CAPTURE']) +sys.exit(subprocess.run([os.environ['FIXTURE_REAL_GIT'], *sys.argv[1:]]).returncode) +""") + git.chmod(0o755) + self.environment = dict(self.environment, PATH=str(capture_bin) + os.pathsep + self.environment["PATH"], + FIXTURE_REAL_GIT=real_git, FIXTURE_ALLOWED_CAPTURE=str(capture)) + self.ssh_key = self.root / "registered-security-key" + for key in keys: + public = self.ssh_key.with_suffix(".pub") + public.write_text(key + "\n") + # Validate the public wire format without requiring a hardware authenticator. + self.call(["ssh-keygen", "-l", "-f", str(public)]) + for signing_only in (False, True): + with self.subTest(key_type=key.split()[0], signing_only=signing_only): + result = self.verify("v1.2.5", registered=not signing_only, signing_only=signing_only) + # The tag uses a different ordinary key: real verification must still reject it. + self.assertNotEqual(0, result.returncode, result.stdout + result.stderr) + self.assertEqual('release-maintainer namespaces="git" ' + key + "\n", capture.read_text()) + + def test_unsigned_tag_blocks_when_enforced(self): + result = self.verify("v1.2.4") + self.assertNotEqual(0, result.returncode) + self.assertIn("annotated", result.stdout + result.stderr) + + def test_unregistered_signature_blocks_when_enforced(self): + result = self.verify(registered=False) + self.assertNotEqual(0, result.returncode) + self.assertIn("not verified", result.stdout + result.stderr) + + def test_default_mode_warns_without_blocking(self): + result = self.verify("v1.2.4", enforce="") + self.assertEqual(0, result.returncode, result.stderr) + self.assertIn("::warning::", result.stdout) + + def test_missing_registered_keys_warns_without_blocking(self): + result = self.verify(enforce="false", registered=False) + self.assertEqual(0, result.returncode, result.stderr) + self.assertIn("::warning::", result.stdout) + + def check_commit(self, tag, commit): + return subprocess.run(["python3", str(SCRIPT.with_name("release.py")), "--root", str(self.repo), + "verify-commit", tag, commit], cwd=self.repo, env=self.environment, + text=True, capture_output=True) + + def test_tag_moved_away_from_event_commit_is_rejected(self): + result = self.check_commit("v1.2.3", self.unreviewed) + self.assertNotEqual(0, result.returncode) + self.assertIn("event commit", result.stderr) + + def test_matching_event_commit_on_master_passes(self): + result = self.check_commit("v1.2.3", self.reviewed) + self.assertEqual(0, result.returncode, result.stderr) + + def test_matching_tag_outside_master_is_rejected(self): + result = self.check_commit("v1.2.8", self.unreviewed) + self.assertNotEqual(0, result.returncode) + self.assertIn("origin/master", result.stderr) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_workflow_mutations.py b/scripts/tests/test_workflow_mutations.py new file mode 100644 index 000000000..d4c74b937 --- /dev/null +++ b/scripts/tests/test_workflow_mutations.py @@ -0,0 +1,126 @@ +"""Check workflow-contract discrimination using disposable workflow copies.""" + +import pathlib +import tempfile +import unittest +from unittest import mock + +import test_workflows as contracts + + +class WorkflowMutationTest(unittest.TestCase): + def setUp(self): + self.files = {name: pathlib.Path(".github/workflows") / name + for name in ("ci_cd.yml", "deploy.yml", "changelog.yml")} + self.files["dependabot.yml"] = pathlib.Path(".github/dependabot.yml") + self.originals = { + name: (contracts.ROOT / filename).read_text() + for name, filename in self.files.items() + } + temporary = tempfile.TemporaryDirectory(prefix="b2-workflow-mutations-") + self.addCleanup(temporary.cleanup) + self.root = pathlib.Path(temporary.name) + (self.root / ".github/workflows").mkdir(parents=True) + for name, content in self.originals.items(): + (self.root / self.files[name]).write_text(content) + + def run_contract(self, method): + result = unittest.TestResult() + with mock.patch.object(contracts, "ROOT", self.root): + contracts.WorkflowTest(method).run(result) + self.assertEqual(1, result.testsRun) + self.assertFalse(result.errors, result.errors) + return result + + def assert_mutation_rejected(self, workflow, before, after, method): + baseline = self.run_contract(method) + self.assertTrue(baseline.wasSuccessful(), baseline.failures) + original = self.originals[workflow] + self.assertEqual(1, original.count(before), "mutation must change exactly one occurrence") + (self.root / self.files[workflow]).write_text(original.replace(before, after, 1)) + result = self.run_contract(method) + self.assertFalse(result.wasSuccessful(), "workflow mutation escaped its contract check") + self.assertTrue(result.failures, "mutation must fail an assertion, not fixture setup") + + def test_missing_pages_artifact_action_is_rejected(self): + self.assert_mutation_rejected( + "ci_cd.yml", "uses: actions/upload-pages-artifact@", "uses: actions/upload-artifact@", + "test_official_pages_actions_and_status_gate_are_connected") + + def test_missing_pages_deployment_is_rejected(self): + self.assert_mutation_rejected( + "ci_cd.yml", "uses: actions/deploy-pages@", "uses: actions/download-artifact@", + "test_official_pages_actions_and_status_gate_are_connected") + + def test_missing_pages_status_command_is_rejected(self): + self.assert_mutation_rejected( + "ci_cd.yml", "curl --fail --show-error --silent --location --max-time 30", + "printf --fail --show-error --silent --location --max-time 30", + "test_official_pages_actions_and_status_gate_are_connected") + + def test_missing_release_creation_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", "gh release create", "true", + "test_release_command_uses_notes_and_each_module_bundle") + + def test_missing_release_notes_argument_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", '--notes-file "$RUNNER_TEMP/release-notes.md" ', "", + "test_release_command_uses_notes_and_each_module_bundle") + + def test_missing_release_assets_argument_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", ' "${assets[@]}"', "", + "test_release_command_uses_notes_and_each_module_bundle") + + def test_missing_release_gate_dependency_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", "needs: release-checks", "needs: []", + "test_release_checks_and_deploy_use_the_same_event_commit") + + def test_missing_publication_dry_run_is_rejected(self): + self.assert_mutation_rejected( + "ci_cd.yml", "--dry-run --no-daemon", "--no-daemon", + "test_publication_task_graph_is_checked_without_publishing") + + def test_missing_release_build_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", "run: ./gradlew build --no-daemon", "run: true", + "test_publish_command_and_signing_secrets_are_preserved") + + def test_missing_signed_tag_verification_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", 'bash scripts/verify-release-tag.sh "$RELEASE_TAG"', "true", + "test_release_gate_commands_are_wired_before_deployment") + + def test_missing_milestone_gate_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", 'run: python3 scripts/release.py milestone "$RELEASE_TAG"', "run: true", + "test_release_gate_commands_are_wired_before_deployment") + + def test_missing_security_gate_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", "run: python3 scripts/release.py security", "run: true", + "test_release_gate_commands_are_wired_before_deployment") + + def test_missing_release_metadata_gate_is_rejected(self): + self.assert_mutation_rejected( + "deploy.yml", + 'python3 scripts/release.py --root "$RUNNER_TEMP/release-metadata" notes "$RELEASE_TAG" > /dev/null', + "true", "test_release_gate_commands_are_wired_before_deployment") + + def test_missing_dependabot_action_updates_is_rejected(self): + self.assert_mutation_rejected( + "dependabot.yml", + ' - package-ecosystem: "github-actions"\n directory: "/"\n' + ' schedule:\n interval: "weekly"\n', "", + "test_dependabot_updates_action_pins_weekly_from_repository_root") + + def test_changelog_pull_request_branch_filter_is_rejected(self): + self.assert_mutation_rejected( + "changelog.yml", " pull_request:\n", " pull_request:\n branches: [master, api-v2, 7.x]\n", + "test_changelog_check_runs_for_pull_requests_without_branch_filters") + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_workflows.py b/scripts/tests/test_workflows.py new file mode 100644 index 000000000..8e91c49bc --- /dev/null +++ b/scripts/tests/test_workflows.py @@ -0,0 +1,225 @@ +"""Release workflow policy and GitHub Pages status contract checks.""" + +import json +import os +import pathlib +import re +import shlex +import shutil +import subprocess +import sys +import tempfile +import unittest + + +ROOT = pathlib.Path(__file__).resolve().parents[2] + + +def step_script(workflow, name): + step = workflow.split(" - name: " + name + "\n", 1)[1] + step = step.split("\n - ", 1)[0] + body = step.split(" run: |\n", 1)[1] + return "\n".join(line[10:] for line in body.splitlines()) + "\n" + + +class WorkflowTest(unittest.TestCase): + def test_changelog_check_runs_for_pull_requests_without_branch_filters(self): + workflow = (ROOT / ".github/workflows/changelog.yml").read_text() + triggers = re.search(r"^on:[ \t]*\n(.*?)(?=^[^\s#]|\Z)", workflow, re.M | re.S) + self.assertIsNotNone(triggers, "changelog workflow must declare its triggers") + pull_request = re.search(r"^ pull_request:[ \t]*\n(.*?)(?=^ \S|\Z)", + triggers.group(1), re.M | re.S) + self.assertIsNotNone(pull_request, "changelog-check must run on pull requests") + self.assertNotRegex(pull_request.group(1), r"(?m)^ branches(?:-ignore)?:") + self.assertIn("\n changelog-check:\n", workflow) + + def test_every_external_action_is_pinned_to_commit(self): + for workflow in (ROOT / ".github/workflows").glob("*.yml"): + for action in re.findall(r"uses:\s*([^\s#]+)", workflow.read_text()): + with self.subTest(workflow=workflow.name, action=action): + self.assertRegex(action, r"^[A-Za-z0-9_./-]+@[0-9a-f]{40}$") + + def test_replaced_community_actions_are_absent(self): + workflows = "\n".join(path.read_text() for path in (ROOT / ".github/workflows").glob("*.yml")) + for action in ("crazy-max/ghaction-github-pages", "crazy-max/ghaction-github-status", "softprops/action-gh-release"): + self.assertNotIn(action, workflows) + + def test_publish_command_and_signing_secrets_are_preserved(self): + workflow = (ROOT / ".github/workflows/deploy.yml").read_text() + deploy = workflow.split("\n deploy:\n", 1)[1] + build_step = " - name: Build and test the release\n" + publish_step = " - name: Deploy to Maven Central\n" + self.assertIn(build_step, deploy) + self.assertIn(publish_step, deploy) + self.assertLess(deploy.index(build_step), deploy.index(publish_step)) + build = deploy.split(build_step, 1)[1].split("\n - ", 1)[0] + command = re.search(r"^ run:[ \t]+(.+)$", build, re.M) + self.assertIsNotNone(command, "release deployment must run the Gradle build") + arguments = shlex.split(command.group(1)) + self.assertEqual("./gradlew", arguments[0]) + self.assertIn("build", arguments[1:]) + self.assertNotIn("--dry-run", arguments) + self.assertIn("./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository createBundle --no-daemon --stacktrace", workflow) + for secret in ("GPG_SIGNING_KEY", "GPG_PASSPHRASE", "SONATYPE_TOKEN_USERNAME", "SONATYPE_TOKEN_PASSWORD"): + self.assertIn("secrets." + secret, workflow) + + def test_release_checks_and_deploy_use_the_same_event_commit(self): + workflow = (ROOT / ".github/workflows/deploy.yml").read_text() + self.assertIn('verify-commit "$RELEASE_TAG" "$GITHUB_SHA"', workflow) + deploy = workflow.split("\n deploy:\n", 1)[1] + self.assertIn("needs: release-checks", deploy) + self.assertIn("ref: ${{ github.sha }}", deploy) + + def test_release_gate_commands_are_wired_before_deployment(self): + workflow = (ROOT / ".github/workflows/deploy.yml").read_text() + checks, deploy = workflow.split("\n release-checks:\n", 1)[1].split("\n deploy:\n", 1) + verification = step_script(checks, "Verify release tag") + self.assertIsNotNone(re.search( + r'^bash scripts/verify-release-tag\.sh "\$RELEASE_TAG"\s*$', verification, re.M), + "release-checks must invoke the signed-tag verifier") + for command in ('milestone "$RELEASE_TAG"', "security"): + with self.subTest(command=command): + self.assertIsNotNone(re.search( + r"^ run: python3 scripts/release\.py " + re.escape(command) + r"\s*$", checks, re.M), + "release-checks must invoke " + command) + metadata = step_script(checks, "Check tag, version, and changelog agreement") + self.assertIn( + 'python3 scripts/release.py --root "$RUNNER_TEMP/release-metadata" notes "$RELEASE_TAG" > /dev/null', + metadata, "release-checks must validate metadata from the event commit") + self.assertIn("needs: release-checks", deploy) + + def test_metadata_gate_runs_against_the_event_commit_and_rejects_mismatches(self): + workflow = (ROOT / ".github/workflows/deploy.yml").read_text() + script = step_script(workflow, "Check tag, version, and changelog agreement") + notes = "## [1.2.3] - 2026-01-01\n\n### Fixed\n\n* Release fixture.\n" + cases = (("v1.2.3", notes, ""), + ("v1.2.4", notes, "tag does not match gradle.properties"), + ("v1.2.3", notes + "\n* Unreviewed notes.\n", "release notes and CHANGELOG.md disagree")) + for tag, changelog, error in cases: + with self.subTest(tag=tag, error=error), tempfile.TemporaryDirectory(prefix="b2-metadata-gate-") as temporary: + root = pathlib.Path(temporary) + (root / ".changes").mkdir() + (root / ".changes/v1.2.3.md").write_text(notes) + (root / "CHANGELOG.md").write_text("# Changelog\n\n" + changelog) + (root / "gradle.properties").write_text("version=1.2.3\n") + (root / "scripts").mkdir() + shutil.copy(ROOT / "scripts/release.py", root / "scripts/release.py") + environment = dict(os.environ, GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM="1") + for args in (("init", "-q"), ("config", "user.name", "Release Fixture"), + ("config", "user.email", "fixture@example.invalid"), ("add", "."), + ("-c", "commit.gpgSign=false", "commit", "-qm", "Release metadata fixture")): + subprocess.run(["git", *args], cwd=root, env=environment, check=True, capture_output=True) + commit = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, env=environment, + text=True).strip() + runner = root / "runner" + runner.mkdir() + environment.update(RELEASE_TAG=tag, GITHUB_SHA=commit, RUNNER_TEMP=str(runner)) + # An uncommitted local version must not replace the immutable event's metadata. + (root / "gradle.properties").write_text("version=9.9.9\n") + result = subprocess.run(["bash", "-e", "-o", "pipefail", "-c", script], cwd=root, + env=environment, text=True, capture_output=True) + if error: + self.assertNotEqual(0, result.returncode, result.stdout + result.stderr) + self.assertIn(error, result.stderr) + else: + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + + def test_dependabot_updates_action_pins_weekly_from_repository_root(self): + configuration = (ROOT / ".github/dependabot.yml").read_text() + updates = re.findall(r"^ - package-ecosystem:.*?(?=^ - |\Z)", configuration, re.M | re.S) + action_updates = [entry for entry in updates if re.match( + r'''^ - package-ecosystem:\s*["']?github-actions["']?\s*(?:#.*)?$''', + entry.splitlines()[0])] + self.assertEqual(1, len(action_updates), "configure exactly one GitHub Actions update entry") + self.assertRegex(action_updates[0], re.compile(r'''^ directory:\s*["']?/["']?\s*(?:#.*)?$''', re.M)) + self.assertRegex(action_updates[0], re.compile( + r'''^ schedule:\s*\n interval:\s*["']?weekly["']?\s*(?:#.*)?$''', re.M)) + + def test_official_pages_actions_and_status_gate_are_connected(self): + workflow = (ROOT / ".github/workflows/ci_cd.yml").read_text() + build, deploy = workflow.split("\n deploy-pages:\n", 1) + self.assertRegex(build, r"uses: actions/upload-pages-artifact@[0-9a-f]{40}\b") + self.assertIn("path: core/build/docs/javadoc", build) + self.assertIn("needs: build", deploy) + self.assertRegex(deploy, r"uses: actions/deploy-pages@[0-9a-f]{40}\b") + self.assertIn("pages: write", deploy) + self.assertIn("id-token: write", deploy) + status = step_script(deploy, "Check GitHub Pages status") + self.assertRegex(status, re.compile( + r"^curl\b.*?https://www\.githubstatus\.com/api/v2/components\.json" + r"\s*\|\s*python3 scripts/release\.py pages-status\b", re.M | re.S)) + + def test_release_command_uses_notes_and_each_module_bundle(self): + workflow = (ROOT / ".github/workflows/deploy.yml").read_text() + script = step_script(workflow, "Create GitHub Release") + for tag, flag in (("v1.2.3", "--latest"), ("v1.2.3-rc.1", "--prerelease")): + with self.subTest(tag=tag), tempfile.TemporaryDirectory(prefix="b2-release-command-") as temporary: + root = pathlib.Path(temporary) + binary = root / "bin" + binary.mkdir() + gh = binary / "gh" + gh.write_text("#!" + sys.executable + "\n" + "import json, os, pathlib, sys\n" + "pathlib.Path(os.environ['GH_CALL']).write_text(json.dumps(sys.argv[1:]))\n") + gh.chmod(0o755) + assets = [] + for module in ("core", "httpclient", "samples"): + path = pathlib.Path(module) / "build/libs" / ("bundle-" + module + ".jar") + (root / path).parent.mkdir(parents=True) + (root / path).write_bytes(b"bundle fixture") + assets.append(str(path)) + notes = root / "release-notes.md" + notes.write_text("Release notes fixture\n") + output = root / "gh-call.json" + environment = dict(os.environ, PATH=str(binary) + os.pathsep + os.environ["PATH"], + RELEASE_TAG=tag, RUNNER_TEMP=str(root), GH_CALL=str(output)) + result = subprocess.run(["bash", "-e", "-o", "pipefail", "-c", script], + cwd=root, env=environment, text=True, capture_output=True) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + self.assertTrue(output.is_file(), "release command did not invoke gh") + arguments = json.loads(output.read_text()) + self.assertEqual(["release", "create", tag], arguments[:3]) + self.assertIn("--verify-tag", arguments) + self.assertIn("--title", arguments) + self.assertEqual(tag, arguments[arguments.index("--title") + 1]) + self.assertIn("--notes-file", arguments) + self.assertEqual(str(notes), arguments[arguments.index("--notes-file") + 1]) + self.assertIn(flag, arguments) + self.assertCountEqual(assets, [value for value in arguments if value.endswith(".jar")]) + + def test_publication_task_graph_is_checked_without_publishing(self): + workflow = (ROOT / ".github/workflows/ci_cd.yml").read_text() + self.assertIn(" - name: Validate publication task graph\n", workflow) + script = step_script(workflow, "Validate publication task graph") + for argument in ("./gradlew", "publishToSonatype", "closeAndReleaseSonatypeStagingRepository", + "createBundle", "--dry-run", "--no-daemon", + "-PsonatypeUsername=dry-run", "-PsonatypePassword=dry-run"): + self.assertIn(argument, script) + + def test_runbook_describes_the_workflow_token_uses(self): + guide = " ".join((ROOT / "RELEASE.md").read_text().split()) + self.assertIn("checkout, signing-key API lookups, milestone reads, and release creation", guide) + + +class PagesStatusTest(unittest.TestCase): + def run_status(self, payload): + return subprocess.run([sys.executable, str(ROOT / "scripts/release.py"), "pages-status"], + input=json.dumps(payload), text=True, capture_output=True) + + def test_operational_pages_passes(self): + result = self.run_status({"components": [{"name": "Pages", "status": "operational"}]}) + self.assertEqual(0, result.returncode, result.stderr) + + def test_major_outage_blocks_deployment(self): + result = self.run_status({"components": [{"name": "Pages", "status": "major_outage"}]}) + self.assertNotEqual(0, result.returncode) + self.assertIn("major outage", result.stderr) + + def test_unreadable_status_is_not_treated_as_operational(self): + result = self.run_status({"components": []}) + self.assertNotEqual(0, result.returncode) + self.assertIn("Pages status", result.stderr) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/verify-release-tag.sh b/scripts/verify-release-tag.sh new file mode 100644 index 000000000..0fce4efb6 --- /dev/null +++ b/scripts/verify-release-tag.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# Verify against the named maintainers' registered keys, isolated from the runner's own keyring. +set -euo pipefail + +tag=${1:?usage: verify-release-tag.sh TAG [MAINTAINERS_FILE]} +maintainers=${2:-.github/signing-maintainers} +enforce=${ENFORCE_SIGNED_TAGS:-false} + +reject() { + if [ "$enforce" = true ]; then + printf 'HOLD: %s\n' "$1" >&2 + exit 1 + fi + printf '::warning::%s (ENFORCE_SIGNED_TAGS is off)\n' "$1" + exit 0 +} + +git check-ref-format "refs/tags/$tag" >/dev/null 2>&1 || reject 'Invalid release tag' +[ "$(git cat-file -t "refs/tags/$tag" 2>/dev/null || true)" = tag ] || reject 'Release tag must be annotated and signed' +[ -r "$maintainers" ] || reject 'Maintainer key registry is unavailable' + +temporary=$(mktemp -d) +cleanup() { + gpgconf --homedir "$temporary/gnupg" --kill all >/dev/null 2>&1 || true + rm -rf "$temporary" +} +trap cleanup EXIT +mkdir -m 700 "$temporary/gnupg" +printf 'no-auto-key-retrieve\nauto-key-locate clear\n' > "$temporary/gnupg/gpg.conf" +export GNUPGHOME="$temporary/gnupg" +touch "$temporary/allowed_signers" + +while IFS= read -r username || [ -n "$username" ]; do + case "$username" in ''|'#'*) continue ;; esac + [[ "$username" =~ ^[a-zA-Z0-9][a-zA-Z0-9-]*$ ]] || reject 'Invalid maintainer username' + if curl --fail --silent --show-error --location --max-time 20 "https://github.com/$username.gpg" > "$temporary/key.gpg" 2>/dev/null; then + if [ -s "$temporary/key.gpg" ] && command -v gpg >/dev/null; then + gpg --batch --import "$temporary/key.gpg" >/dev/null 2>&1 || true + fi + fi + curl --fail --silent --show-error --location --max-time 20 "https://github.com/$username.keys" > "$temporary/key.ssh" 2>/dev/null || true + # Signing-only SSH keys are distinct from the authentication keys served by .keys. + gh api --paginate "users/$username/ssh_signing_keys?per_page=100" --jq '.[].key' >> "$temporary/key.ssh" 2>/dev/null || true + while IFS= read -r key; do + case "$key" in + ssh-*|ecdsa-*|sk-ssh-*|sk-ecdsa-*) printf 'release-maintainer namespaces="git" %s\n' "$key" >> "$temporary/allowed_signers" ;; + esac + done < "$temporary/key.ssh" +done < "$maintainers" + +if git -c gpg.ssh.allowedSignersFile="$temporary/allowed_signers" verify-tag -- "$tag" > "$temporary/verification" 2>&1; then + printf 'release tag: verified against a registered maintainer key\n' +else + reject 'Release tag signature not verified against registered maintainer keys; enroll keys before enforcement' +fi