Update PyPI publishing workflow to use Trusted Publishing across Echostack packages

[lsetiawan]

Updated to reflect organization-level tracking

Summary

Echostack packages currently use long-lived API tokens (PYPI_API_TOKEN and TEST_PYPI_API_TOKEN) stored as repository secrets to authenticate with PyPI and TestPyPI. These should be migrated to Trusted Publishing, which is more secure and is now the recommended approach by PyPI.

This issue tracks the migration at the organization level. Repository-specific issues and pull requests should implement the required changes for each package.

Motivation

Supply chain attacks targeting PyPI packages are increasing. A recent example is the LiteLLM/Telnyx supply chain attack, where a compromised token was used to publish a malicious package version. Long-lived API tokens are vulnerable to:

• Secret exfiltration — if a token leaks (via logs, compromised CI, or a malicious PR), an attacker can publish arbitrary package versions.
• No scope boundaries — API tokens don't inherently restrict which workflow or repository can use them.

Trusted Publishing eliminates these risks by using short-lived OIDC tokens scoped to a specific GitHub repository, workflow, and (optionally) environment. No secrets need to be stored or rotated.

Current workflow issues

Current PyPI publishing workflows in Echostack repositories:

1. Publish to TestPyPI using password: ${{ secrets.TEST_PYPI_API_TOKEN }}
2. Publish to PyPI using password: ${{ secrets.PYPI_API_TOKEN }}
3. Do not declare permissions: id-token: write (required for OIDC)
4. May not use GitHub Actions environment (recommended for an additional layer of protection, e.g., required reviewers)

Repository tracking

• echopype
• echoshader
• echodataflow
• echoregions
• echopop
• Other published Echostack packages

Proposed changes

1. Configure Trusted Publishers on PyPI and TestPyPI

Follow the setup guides:

• PyPI: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
• TestPyPI: Same process on https://test.pypi.org

For each published package, add a new trusted publisher with:

• Owner: echostack-org
• Repository: <repository>
• Workflow name: the repository publishing workflow (e.g. pypi.yaml)
• Environment (optional but recommended): e.g., pypi / testpypi

2. Update the workflow

Key changes needed in each repository publishing workflow:

• Remove password: lines from both publish steps
• Add permissions: id-token: write to the publish jobs
• Optionally add environment: to the publish jobs for additional protection

Example for the production publish job:

publish-pypi:
  name: Push package to production PyPI
  needs: test-built-dist
  if: startsWith(github.ref, 'refs/tags')
  runs-on: ubuntu-latest
  environment: pypi
  permissions:
    id-token: write
  steps:
    - uses: actions/download-artifact@v8
      with:
        name: releases
        path: dist
    - name: Publish to PyPI
      uses: pypa/gh-action-pypi-publish@v1.13.0

Similarly for the TestPyPI publish step.

3. Clean up old secrets

Once trusted publishing is verified to work, remove the PYPI_API_TOKEN and TEST_PYPI_API_TOKEN repository secrets.

References

• PyPI Trusted Publishers documentation
• Adding a trusted publisher to an existing project
• GitHub Actions — pypa/gh-action-pypi-publish trusted publishing docs
• LiteLLM/Telnyx supply chain attack incident report

[LOCEANlloydizard]

Hi @lsetiawan, nice!! Really nice to see this security feature. We also recently had an issue with the PyPI build, so I made a small fix in echostack-org/echopype#1643 to get it to pass, and was thinking we should also rework the build, so this comes at a good time!

BTW, we should probably do the same for the other Echostack repositories as well.. For example, we currently have an issue on Echoshader (and likely on others too) so it could be good to update both the code and security? cheers!