Warning, /swf-testbed/docs/automated_testpypi_publishing.md is written in an unsupported language. File is not indexed.
0001 # Automated Publishing to TestPyPI with GitHub Actions
0002
0003 This document details the procedure for automatically publishing Python packages to TestPyPI using a GitHub Actions workflow. This is the recommended method for releasing new versions of components like `swf-common-lib`.
0004
0005 The process relies on a workflow that triggers when a new version tag (e.g., `v0.0.10`) is pushed to the repository.
0006
0007 ## 1. GitHub Actions Workflow
0008
0009 The core of the automation is the `.github/workflows/publish-to-testpypi.yml` file.
0010
0011 ```yaml
0012 name: Publish Python Package to TestPyPI
0013
0014 on:
0015 push:
0016 tags:
0017 - 'v*'
0018
0019 jobs:
0020 build-and-publish:
0021 runs-on: ubuntu-latest
0022 permissions:
0023 contents: read
0024
0025 steps:
0026 - name: Checkout repository
0027 uses: actions/checkout@v4
0028
0029 - name: Set up Python
0030 uses: actions/setup-python@v4
0031 with:
0032 python-version: '3.9'
0033
0034 - name: Install dependencies
0035 run: |
0036 python -m pip install --upgrade pip
0037 pip install build twine
0038
0039 - name: Build package
0040 run: python -m build
0041
0042 - name: Publish package to TestPyPI
0043 env:
0044 TWINE_USERNAME: __token__
0045 TWINE_PASSWORD: ${{ secrets.TESTPYPI_API_TOKEN }}
0046 run: twine upload --repository testpypi dist/*
0047 ```
0048
0049 ### Key Components:
0050
0051 - **`on: push: tags: - 'v*'`**: This trigger ensures the workflow only runs when a tag starting with `v` is pushed.
0052 - **`TWINE_USERNAME: __token__`**: This is the critical setting for authenticating with TestPyPI's API. The username must be the literal string `__token__`.
0053 - **`TWINE_PASSWORD: ${{ secrets.TESTPYPI_API_TOKEN }}`**: The password must be a TestPyPI API token, stored as an encrypted secret in the GitHub repository's settings.
0054
0055 ## 2. Repository Secret Configuration
0056
0057 For the workflow to authenticate, you must create a repository secret named `TESTPYPI_API_TOKEN`.
0058
0059 1. **Generate a Token**: Go to your TestPyPI account settings and generate a new API token: [https://test.pypi.org/manage/account/token/](https://test.pypi.org/manage/account/token/).
0060 2. **Add to GitHub**: In your GitHub repository, go to `Settings` > `Secrets and variables` > `Actions`. Click `New repository secret` and add the token with the name `TESTPYPI_API_TOKEN`.
0061
0062 ## 3. Publishing Workflow
0063
0064 Once the workflow and secret are in place, publishing a new version is simple:
0065
0066 1. **Increment Version**: Update the `version` in your `pyproject.toml` file.
0067 ```toml
0068 # pyproject.toml
0069 version = "0.0.11"
0070 ```
0071 2. **Commit the Change**:
0072 ```bash
0073 git commit -am "Increment version to 0.0.11"
0074 ```
0075 3. **Tag the Commit**: Create a new git tag that matches the version number.
0076 ```bash
0077 git tag v0.0.11
0078 ```
0079 4. **Push to GitHub**: Push the commit and the new tag.
0080 ```bash
0081 git push && git push --tags
0082 ```
0083
0084 Pushing the tag will automatically trigger the GitHub Action, which builds the package and publishes it to TestPyPI. You can monitor its progress in the "Actions" tab of your repository.
