Skip to content

Publishing (PyPI Trusted Publisher)

WorldFlux uses PyPI Trusted Publishing (OIDC) from GitHub Actions.

Workflow Model

  • Build artifacts in a dedicated build job.
  • Validate release metadata (tag/version/changelog) before build.
  • Validate fixed parity artifacts (DreamerV3 + TD-MPC2) before build/publish.
  • Validate parity suite policy (reports/parity/suite_policy.json) against lock + aggregate before build/publish.
  • Generate verification report artifacts (verification-report.json / .md) and attach to release workflow artifacts.
  • Publish in separate jobs with id-token: write.
  • No PyPI API token/password is required in GitHub secrets.

See workflow: .github/workflows/release.yml

PyPI-side Setup (one-time)

  1. Open your project on PyPI.
  2. Go to Publishing -> Add a new pending publisher.
  3. Set:
  4. Owner: worldflux
  5. Repository: WorldFlux
  6. Workflow: release.yml
  7. Environment (optional but recommended): pypi
  8. Save publisher and run a test release.

For TestPyPI, repeat the same setup on TestPyPI and map the testpypi environment.

Release Procedure

  1. Ensure CI is green on main.
  2. Update CHANGELOG.md and version metadata.
  3. Validate release metadata locally:
  4. uv run python scripts/check_release_metadata.py --tag vX.Y.Z
  5. (Optional) Run parity pipeline report generation:
  6. uv run bash scripts/parity/fetch_oracles.sh --oracle-root /root/oracles --dreamer-commit <sha> --tdmpc2-commit <sha> --copy-to artifacts/upstream
  7. worldflux parity campaign run benchmarks/parity/campaign/dreamer_atari100k.yaml --mode worldflux --device cuda --seeds 0,1,2,3,4 --resume
  8. worldflux parity campaign run benchmarks/parity/campaign/tdmpc2_dmcontrol39.yaml --mode worldflux --device cuda --seeds 1,2,3 --resume
  9. worldflux parity run ...
  10. worldflux parity aggregate ...
  11. worldflux parity report ...
  12. Validate release parity gate against fixed artifacts:
  13. uv run python scripts/validate_parity_artifacts.py --run reports/parity/runs/dreamer_atari100k.json --run reports/parity/runs/tdmpc2_dmcontrol39.json --aggregate reports/parity/aggregate.json --lock reports/parity/upstream_lock.json --required-suite dreamer_atari100k --required-suite tdmpc2_dmcontrol39 --max-missing-pairs 0
  14. Validate suite policy gate:
  15. uv run python scripts/check_parity_suite_coverage.py --policy reports/parity/suite_policy.json --lock reports/parity/upstream_lock.json --aggregate reports/parity/aggregate.json --enforce-pass
  16. Create a GitHub release tag.
  17. Publish workflow runs automatically on release publication.

Troubleshooting

  • OIDC permission error: verify id-token: write on publish jobs.
  • Publisher not recognized: verify owner/repo/workflow/environment names exactly.
  • Artifact issues: ensure build job uploaded dist/ and publish jobs download it.
  • Parity gate fail:
  • Check reports/parity/aggregate.json for ci_upper_ratio > margin_ratio or missing pairs.
  • Check reports/parity/upstream_lock.json commit pins match run artifacts.
  • Check reports/parity/suite_policy.json required suites align with lock and aggregate.