PyPI Publishing & Trusted Publishing Guide

This guide covers building, testing, and publishing TraceForge to the Python Package Index (PyPI) using modern PyPA standards and GitHub Actions OIDC Trusted Publishing.

1. Distribution & Package Overview

  • PyPI Distribution Name: traceforge-osint

  • Import Package: traceforge

  • CLI Executable: traceforge

  • Version: 1.0.0 (synchronously bound to VERSION and pyproject.toml)

Users install TraceForge via:

pip install traceforge-osint
# or
pipx install traceforge-osint

And run:

traceforge --version
# or
python3 -m traceforge --version

2. Local Package Build & Validation

To build and validate the source distribution (.tar.gz) and wheel (.whl) locally:

# Clean, build, validate with twine, and run clean-env smoke test:
bash scripts/build_package.sh

This runs:

  1. python3 -m build --sdist --wheel --outdir dist/

  2. python3 -m twine check dist/*

  3. Installs the built wheel into a temporary isolated virtual environment (/tmp/traceforge-pypi-test-*).

  4. Executes traceforge --version, traceforge --help, catalog lookups, and standalone IOC extractions from outside the repository.

3. GitHub Actions Trusted Publishing Setup (OIDC)

TraceForge uses PyPI Trusted Publishing, eliminating the need for long-lived API tokens or passwords stored in GitHub Secrets.

One-Time PyPI Configuration (Maintainer Checklist):

  1. Log into https://pypi.org with the project owner account.

  2. Navigate to Account Settings → Publishing → Add a new publisher.

  3. Select GitHub Actions:

    • PyPI Project Name: traceforge-osint

    • Owner: paman7647

    • Repository Name: TraceForge

    • Workflow name: publish-pypi.yml

    • Environment name: pypi

  4. Click Add Publisher.

4. Releasing to PyPI

When ready to publish a new official release:

# 1. Ensure beta branch passes all validation checks
traceforge doctor


# 2. Merge beta into master
git checkout master
git merge --ff-only beta

# 3. Create a semantic version release tag
git tag -a v1.0.0 -m "Release TraceForge 1.0.0"

# 4. Push tag to GitHub
git push origin master --tags

GitHub Actions will automatically trigger .github/workflows/publish-pypi.yml:

  1. Check out the release tag.

  2. Build the wheel and sdist.

  3. Validate archives with twine check.

  4. Publish artifacts to PyPI via OIDC token exchange.

5. Testing on TestPyPI

To test publication on TestPyPI before a production release:

  1. Configure a Trusted Publisher on https://test.pypi.org for environment testpypi.

  2. Trigger the .github/workflows/publish-testpypi.yml workflow via GitHub Actions Workflow Dispatch (manual trigger).

  3. Verify test installation:

    pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ traceforge-osint