Publicación de una versión (para mantenedores)¶
Cómo se publica una versión del harness, qué hace cada flujo de GitHub Actions y qué debe configurar el mantenedor a mano para publicar también en PyPI. La versión en inglés de los pasos de cuenta está en Maintainer setup.
Canales de distribución¶
GitHub Packages no tiene un registro para paquetes de Python, así que el harness se distribuye por tres canales:
| Canal | Qué publica | Flujo | Estado |
|---|---|---|---|
| GitHub Releases | wheel, sdist, SHA256SUMS, SBOM SPDX, atestación de procedencia (también como .intoto.jsonl), firmas Sigstore .sigstore.json |
release.yml |
Siempre, con cada etiqueta v* |
| GHCR | Imagen ghcr.io/sebasbarrera/harness-engineering multi-arquitectura, con SBOM y atestación |
docker.yml |
Siempre, con cada etiqueta v* |
| PyPI | El mismo wheel y sdist, con un Trusted Publisher (sin tokens) | release.yml, trabajo publish-pypi |
Solo si el mantenedor lo habilita (abajo) |
El flujo de una versión¶
El flujo de ramas está en CONTRIBUTING.md y CLAUDE.md. Para una versión:
- Desde
developcrearelease/x.y.z. Sube la versión enpyproject.toml(version) y ensrc/governed_harness/__init__.py(__version__): el flujo compara la etiqueta conpyproject.toml, yharness --versionimprime__version__. Pasa elCHANGELOG: lo que estaba en## Unreleasedpasa a una sección## x.y.z. - Espera a que todos los trabajos bloqueantes de todos los flujos estén en verde en la rama.
- Mezcla
release/x.y.zenmaincon un commit de merge (git merge --no-ff). - Crea la etiqueta anotada y sin firma
vx.y.zsobre ese commit y súbela. Es lo que dispara los flujos de publicación.
git tag -a vx.y.z -m "vx.y.z"
git push origin vx.y.z
- Mezcla
mainde vuelta endevelop.
Nunca muevas ni reescribas la etiqueta v0.8.0 (una iteración anterior y obsoleta de la tesis, reproducible) ni la historia publicada.
Qué hace release.yml¶
Se ejecuta al subir una etiqueta v* (salvo v0.8.0). El trabajo release (nombre «build, attest and publish»):
- Comprueba que la etiqueta coincide con la versión de
pyproject.toml; si no, falla. - Construye el sdist y el wheel con
python -m buildy los revisa contwine check --strict. - Genera el SBOM SPDX con
anchore/sbom-action. - Atestigua la procedencia de los distribuibles con
actions/attest-build-provenance. - Firma el wheel y el sdist sin llaves con
sigstore/gh-action-sigstore-python(identidad OIDC del flujo, permisoid-token: writeque el trabajo ya tenía para la atestación), comprueba cada firma contra la identidadhttps://github.com/<repo>/.github/workflows/release.yml@<ref>y deja<archivo>.sigstore.jsonendist/. Copia la atestación de procedencia adist/governed-agent-harness-<versión>.intoto.jsonl. Son los archivos que busca la comprobación Signed-Releases de OpenSSF Scorecard, que no ve las atestaciones de GitHub. - Guarda el wheel y el sdist como artefacto del flujo (
python-distributions, 7 días), para el trabajo de PyPI. - Copia el SBOM a
dist/, escribeSHA256SUMS, genera las notas desde los Conventional Commits (scripts/release_notes.py) y agrega a las notas la sección de verificación. - Crea el release de GitHub con todo lo de
dist/(gh release create --verify-tag).
docker.yml hace en paralelo su trabajo: construye y escanea la imagen y, con una etiqueta v*, la publica en GHCR para linux/amd64 y linux/arm64 con SBOM y atestación.
El trabajo publish-pypi¶
Va después de release, solo sobre etiquetas y solo si la variable del repositorio PYPI_PUBLISH vale true:
needs: release: no se ejecuta si la construcción falló.if: vars.PYPI_PUBLISH == 'true' && startsWith(github.ref, 'refs/tags/v'): con la variable ausente o distinta detrue, el trabajo se omite y el release se crea igual. Así el flujo no se rompe mientras el Trusted Publisher no está configurado.environment: pypi: el entorno de GitHub que vincula el publicador de confianza y permite exigir aprobación manual.permissions: id-token: writey nada más: es el permiso que PyPI usa para el intercambio OIDC. Este trabajo no recibecontentsniattestations, y el nivel superior del flujo sigue sin permisos (el trabajoreleasetiene los suyos para el release y la atestación).- Descarga el artefacto
python-distributionsque construyó y atestó el trabajoreleasey lo sube conpypa/gh-action-pypi-publish, fijada por el SHA completo del commit dev1.14.2(dc37677b2e1c63e2034f94d8a5b11f265b73ba33). No reconstruye nada: lo que llega a PyPI es el mismo archivo del release.
El SHA se obtuvo con gh api repos/pypa/gh-action-pypi-publish/git/ref/tags/v1.14.2 (una etiqueta anotada, cuyo objeto es a892a5a…) y de ahí git/tags/<sha> para llegar al commit; la última versión estable al hacerlo era v1.14.2.
Configuración única en PyPI (a mano)¶
Esto no se puede automatizar: requiere tu cuenta de PyPI y de GitHub.
- Crea una cuenta en pypi.org y activa la verificación en dos pasos.
- Comprueba que el nombre
governed-agent-harnessesté libre en PyPI (no pude consultarlo sin red). Si lo ocupa otro proyecto, hay que cambiarnameenpyproject.toml, la URL del entorno enrelease.ymly estas guías. - En PyPI ve a Your account → Publishing y agrega un publicador pendiente (pending publisher), porque el proyecto aún no existe:
- Project name:
governed-agent-harness - Owner:
SebasBarrera - Repository name:
harness-engineering - Workflow name:
release.yml - Environment name:
pypi - En GitHub, en Settings → Environments, crea el entorno
pypi(si no existe, GitHub lo crea la primera vez que se usa). Recomendado: agrégate como revisor obligatorio, para aprobar a mano cada publicación en PyPI, porque una versión publicada no se puede volver a subir. - Activa la publicación con la variable del repositorio:
gh variable set PYPI_PUBLISH --body true --repo SebasBarrera/harness-engineering
- Sube la siguiente etiqueta
v*(el flujo del apartado anterior). El trabajopublish-pypiaparece en la ejecución derelease.yml; la primera vez crea el proyecto en PyPI a partir del publicador pendiente. - Comprueba en un entorno limpio:
python3.12 -m venv /tmp/pypi-check && /tmp/pypi-check/bin/pip install governed-agent-harness==x.y.z
/tmp/pypi-check/bin/harness --version
Para desactivar la publicación, borra la variable (gh variable delete PYPI_PUBLISH) o ponla en otro valor. Las versiones que ya estén en PyPI no se retiran; se pueden marcar como yanked desde la página del proyecto.
La publicación solo ocurre para etiquetas posteriores a activar la variable: la etiqueta v1.0.0 ya tiene su release y su flujo no contiene este trabajo, así que esa versión no estará en PyPI salvo que se publique aparte.
Qué se comprobó¶
twine check --strictpasó con el wheel y el sdist construidos de este repositorio (versión 1.0.0). El mismo comando está enrelease.yml.actionlintyzizmor --offline(la versión fijada enlint.yml, 1.30.1) no reportaron hallazgos sobrerelease.ymlcon el trabajo nuevo.- No se pudo ejecutar el flujo completo: requiere una etiqueta, GitHub Actions y la configuración de PyPI del mantenedor. El camino sin la variable (el trabajo se omite) es el comportamiento de
ifde Actions con una variable ausente; no se observó en una ejecución real. - Metadatos: el nombre
governed-agent-harness, la descripción, elREADME.mdcomo descripción larga, la licencia, las clasificaciones y las URL del proyecto están enpyproject.toml.setuptoolsreciente avisa de quelicense = {text = ...}está en desuso; es solo un aviso de construcción y se puede migrar a una expresión SPDX más adelante.