diff --git a/CHANGELOG.md b/CHANGELOG.md index 868a547..174d1b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,34 @@ After every task with file changes, briefly record what changed and why: feature ### Changed +- Synchronized the v1.7.9 publication documentation with current `main` after + merged Dependabot updates, preserving dependency/workflow changes and the + immutable release tag. Kept the documentation PR separate from unrelated + local runtime, installer, and AI-KIT files. +- Published GitHub release `v1.7.9` from its unchanged existing source tag on + 2026-11-04, with English release notes covering the tagged changes and Python + distribution. The release triggered the existing archive-signing and container + workflows without repeating PyPI publication. Both workflows succeeded; + independently verified both downloaded signatures with exact identity/issuer + checks and matched all four asset digests. Recorded the publication and + signed-asset evidence in the Wiki, project navigation, context, and continuity + skill so future work does not recreate the release or move its tag. +- Registered the production PyPI Trusted Publisher for `shellharbor-watchdog`, + bound to `shellharbor/watchdog`, `pypi-publish.yml`, and environment `pypi`, + after explicit owner confirmation. Published wheel/sdist `1.7.9` through + GitHub Actions after owner deployment approval, without an API-token secret + or changing the source tag. Verified artifact hashes, publisher-attestation + identities, and a clean non-root Linux install/runtime smoke using only the + production index. Updated README, Wiki, navigation, and continuity guidance + to document the now-available PyPI installation and avoid duplicate uploads. +- Created the new annotated `v1.7.9` source tag and successfully published its + wheel/sdist to TestPyPI through environment-bound GitHub OIDC. Matched both + files to CI artifact hashes, checked publish-attestation identities, and + verified non-root Linux installation, CLI/module commands, validation, dry-run + state behavior, a healthy cycle, and saved-state status. Added a test-index + installation example and synchronized project context/skills. Production + publication followed separately; no GitHub release or Docker publication + was dispatched as part of the Python package uploads. - Replaced obsolete required Go check contexts on `main` with the actual Bash regression/lint, Python 3.11/3.12 launcher, wheel/sdist installation, and GitHub Actions CodeQL checks, bound to the GitHub Actions integration. @@ -40,7 +68,7 @@ After every task with file changes, briefly record what changed and why: feature `main`, with explicit owner approval for production. Clarified the distinction between the workflow execution branch and the immutable release-tag input to avoid deployment-policy failures. Production publisher registration and - distribution uploads remain separate, uncompleted steps. + distribution uploads use separate, explicitly authorized steps. - Extended dependency-update and supply-chain checks to the Python backend, packaging lock, and least-privilege publisher. Added a safe example and Python package Wiki guide; synchronized README, release instructions, project skills, diff --git a/README.md b/README.md index 9b8cc16..3618fc1 100644 --- a/README.md +++ b/README.md @@ -128,21 +128,21 @@ engine, not a rewritten monitor. It requires Python 3.11+ on Linux (including WSL), Bash 4.3+, Mike Farah yq v4, curl, flock, and GNU coreutils. Native installation, systemd, Docker, and Kubernetes do not gain a Python dependency. -Install from this checkout before its first PyPI publication: +Install the published [v1.7.9 package from PyPI](https://pypi.org/project/shellharbor-watchdog/1.7.9/): ```bash python3 -m venv .venv -.venv/bin/python -m pip install . +.venv/bin/python -m pip install shellharbor-watchdog==1.7.9 .venv/bin/python -m shellharbor_watchdog --version .venv/bin/python -m shellharbor_watchdog validate -c /etc/watchdog/config.yaml .venv/bin/shellharbor-watchdog status -c /etc/watchdog/config.yaml --json .venv/bin/shellharbor-watchdog-discover --help ``` -After publication, replace `pip install .` with -`pip install shellharbor-watchdog`. Do **not** install the unrelated `watchdog` -filesystem-event package. This repository's package is not published by -building it locally or creating a GitHub release. +For local development, use `pip install .` from this checkout instead. Do +**not** install the unrelated `watchdog` filesystem-event package. Publication +uses a separate manually approved GitHub Actions workflow with Trusted +Publishing; local builds and GitHub releases do not upload to PyPI. The Python launchers forward the existing CLI arguments literally and replace themselves with Bash, retaining signals, standard streams, and exit codes @@ -155,6 +155,12 @@ See the [Python package guide](wiki/Python-Package.md) for installation, examples, tests, and manual TestPyPI/PyPI Trusted Publishing. A safe first configuration is available in [`examples/python-package.yaml`](examples/python-package.yaml). +The [verified production publication](wiki/Python-Package.md#verified-pypi-publication) +includes wheel/sdist hash checks, publisher-attestation identity checks, and +clean Linux installation/runtime tests. The earlier +[TestPyPI trial](wiki/Python-Package.md#verified-testpypi-trial) remains separate; +do not use the test index for production deployment. + ## Run Watchdog in Docker Docker is an additional deployment option, not a replacement for the native diff --git a/docs/fuzzing-and-release-signatures.md b/docs/fuzzing-and-release-signatures.md index 5d7f0bb..b3de8e4 100644 --- a/docs/fuzzing-and-release-signatures.md +++ b/docs/fuzzing-and-release-signatures.md @@ -92,5 +92,17 @@ Different existing bytes or invalid signatures require maintainer investigation; the workflow never uses `--clobber`. Old tags remain unchanged. Docker image publication, SBOMs, and BuildKit provenance retain their separate workflow. -The first keyless signature and Scorecard's detection require a real GitHub -release run. Local crypto tests cannot create or prove a GitHub OIDC identity. +The first real keyless signing run succeeded on 2026-11-04: +[run 41762886410](https://github.com/shellharbor/watchdog/actions/runs/41762886410) +attached all four signed files to +[release v1.7.9](https://github.com/shellharbor/watchdog/releases/tag/v1.7.9). +The workflow verified the exact release identity and issuer before uploading. +Use `version=1.7.9` with the verification commands above for that release. +The downloaded archive's SHA-256 matches its published `SHA256SUMS`. +Independent local Cosign 3.1.3 verification of the downloaded archive and +checksum file also passed, with the exact workflow/tag identity and GitHub +OIDC issuer enforced. All four downloaded file digests match GitHub metadata. + +Scorecard's detection is a separate external observation; it is not established +by a successful signing run alone. Local disposable-key crypto tests cannot +create or prove a GitHub OIDC identity. diff --git a/wiki/Python-Package.md b/wiki/Python-Package.md index e4e72bd..dd7092d 100644 --- a/wiki/Python-Package.md +++ b/wiki/Python-Package.md @@ -16,7 +16,20 @@ scripts at startup, auto-install OS tools, rewrite checks, change state formats, create a daemon, or register cron/systemd jobs. Native and container deployments still work without Python. -## Install from a checkout before publication +## Install from PyPI + +The published package is available from the ordinary production index: + +```bash +python3 -m venv .venv +.venv/bin/python -m pip install shellharbor-watchdog==1.7.9 +.venv/bin/python -m shellharbor_watchdog --version +``` + +No TestPyPI or additional index is needed. Install the Linux dependencies listed +above separately; the package does not install OS tools. + +## Install from a checkout From the repository root on Linux: @@ -32,13 +45,6 @@ The example checks only `true`; validation and the dry run do not write service state. For production, replace the example with a reviewed configuration using absolute paths owned by the monitoring service account. -After the first PyPI publication, installation by name becomes available: - -```bash -python3 -m venv .venv -.venv/bin/python -m pip install shellharbor-watchdog -``` - For an already built local wheel, no index or Python dependency downloads are needed at installation time: @@ -109,7 +115,8 @@ and bundled metadata. It uploads artifacts for inspection but never to PyPI. Publication is separate from building, GitHub releases, and container publishing. The `Publish Python package` workflow has only a manual trigger and defaults to -TestPyPI. Nothing has been uploaded merely by adding these files. +TestPyPI. Adding files, building locally, or creating a GitHub release does not +upload distributions to either index. 1. Register your PyPI/TestPyPI accounts. The repository's GitHub environments `testpypi` and `pypi` allow deployments only from the `main` branch. Production @@ -144,3 +151,66 @@ actual OIDC publication is verified only by a real authorized run. See the official [Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/) and [pending publisher instructions](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/). + +## Verified PyPI publication + +Version [1.7.9](https://pypi.org/project/shellharbor-watchdog/1.7.9/) was +published on 2026-10-23 by +[GitHub Actions run 39975552350](https://github.com/shellharbor/watchdog/actions/runs/39975552350), +using the existing immutable `v1.7.9` tag. The owner explicitly confirmed the +production Trusted Publisher and approved the `pypi` deployment in GitHub. +The publisher is now active for `shellharbor/watchdog`, `pypi-publish.yml`, and +environment `pypi`; no API-token secret was created. + +The build passed release preflight, launcher/installed-package tests, and strict +Twine validation. Published wheel/sdist SHA-256 values match both this run's +artifacts and the TestPyPI trial. PyPI's Integrity API reports the expected +GitHub repository/workflow/environment in one publish attestation per file. +This metadata check over HTTPS is not an independent local cryptographic +verification of the attestations. + +A fresh non-root Linux/Python 3.11 container with a read-only root filesystem +installed `shellharbor-watchdog==1.7.9` only from `https://pypi.org/simple/`, +without an extra index or Python runtime dependencies. Console/module versions, +both discovery entrypoints, validation, dry-run state behavior, a healthy cycle, +and saved-state JSON status passed. Validation created no runtime paths; +dry-run retained the native operational log/lock but no service state. + +Do not rerun the completed upload, overwrite its filenames, or move its tag. +Future package versions require a new reviewed release tag and a new manually +approved publication. GitHub releases, Docker images, and release-archive +signatures remain separate workflows. + +[GitHub release v1.7.9](https://github.com/shellharbor/watchdog/releases/tag/v1.7.9) +was subsequently published on 2026-11-04 from the unchanged source tag. This +triggered the existing archive-signing and container workflows, not another +PyPI upload. + +## Verified TestPyPI trial + +Version [1.7.9](https://test.pypi.org/project/shellharbor-watchdog/1.7.9/) was +published on 2026-10-23 by the manual +[GitHub Actions run](https://github.com/shellharbor/watchdog/actions/runs/39956141897). +Both wheel and source archive match the tested CI artifacts by SHA-256, and +TestPyPI exposes publish attestations identifying the expected repository, +workflow, and `testpypi` environment. This is not a production PyPI publication. + +Try it on Linux/WSL with the ordinary Watchdog dependencies already installed: + +```bash +python3 -m venv .venv-testpypi +.venv-testpypi/bin/python -m pip --isolated install \ + --index-url https://test.pypi.org/simple/ --no-deps --only-binary=:all: \ + shellharbor-watchdog==1.7.9 +.venv-testpypi/bin/shellharbor-watchdog --version +.venv-testpypi/bin/python -m shellharbor_watchdog --version +.venv-testpypi/bin/shellharbor-watchdog-discover --help +``` + +No additional index is needed because this package has no Python runtime +dependencies. A non-root, read-only-root Linux container verified installation, +validation, a dry run without service state, a healthy cycle, and saved-state +status. As in the native engine, the dry run retains its operational log/lock; +`validate` creates no runtime files. TestPyPI data may be pruned: use the +[test-index guide](https://packaging.python.org/en/latest/guides/using-testpypi/) +for experimentation, not production deployment.