gh-action-pypi-publish/README.md

102 lines
3.3 KiB
Markdown
Raw Normal View History

2019-03-28 03:58:36 +08:00
# PyPI publish GitHub Action
This action allows you to upload your [Python distribution packages](
https://packaging.python.org/glossary/#term-distribution-package)
in the `dist/` directory to PyPI.
2019-09-27 19:37:19 +08:00
This text suggests a minimalistic usage overview. For more detailed
walkthrough check out the [PyPA guide].
2019-03-28 03:58:36 +08:00
## Usage
2019-09-16 19:01:16 +08:00
To use the action add the following step to your workflow file (e.g.
`.github/workflows/main.yml`)
```yml
- name: Publish a Python distribution to PyPI
2019-08-23 19:20:45 +08:00
uses: pypa/gh-action-pypi-publish@master
with:
user: __token__
password: ${{ secrets.pypi_password }}
2019-03-28 03:58:36 +08:00
```
> **Pro tip**: instead of using branch pointers, like `master`, pin versions of
Actions that you use to tagged versions or sha1 commit identifiers. This will
make your workflows more secure and better reproducible, saving you from sudden
and unpleasant surprises.
A common use case is to upload packages only on a tagged commit, to do so add a
filter to the step:
2019-03-28 03:58:36 +08:00
```yml
if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
```
So the full step would look like:
```yml
- name: Publish package
if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
2019-08-23 19:20:45 +08:00
uses: pypa/gh-action-pypi-publish@master
with:
user: __token__
password: ${{ secrets.pypi_password }}
```
The example above uses the new [API token](https://pypi.org/help/#apitoken)
feature of PyPI, which is recommended to restrict the access the action has.
2019-09-25 05:04:57 +08:00
The secret used in `${{ secrets.pypi_password }}` needs to be created on the
settings page of your project on GitHub. See [Creating & using secrets].
2019-03-28 03:58:36 +08:00
2019-09-12 20:06:55 +08:00
## Non-goals
This GitHub Action [has nothing to do with _building package
distributions_]. Users are responsible for preparing dists for upload
by putting them into the `dist/` folder prior to running this Action.
2019-09-15 15:16:54 +08:00
## Advanced release management
For best results, figure out what kind of workflow fits your
project's specific needs.
2019-09-16 19:01:16 +08:00
2019-09-15 15:16:54 +08:00
For example, you could implement a parallel workflow that
2019-09-19 16:04:14 +08:00
pushes every commit to TestPyPI or your own index server,
2019-09-15 15:16:54 +08:00
like `devpi`. For this, you'd need to (1) specify a custom
`repository_url` value and (2) generate a unique version
number for each upload so that they'd not create a conflict.
2019-09-16 19:01:16 +08:00
The latter is possible if you use `setuptools_scm` package but
2019-09-15 15:16:54 +08:00
you could also invent your own solution based on the distance
to the latest tagged commit.
2019-09-16 19:01:16 +08:00
You'll need to create another token for a separate host and then
[save it as a GitHub repo secret][Creating & using secrets].
2019-09-15 21:24:35 +08:00
2019-09-15 15:16:54 +08:00
The action invocation in this case would look like:
```yml
2019-09-19 16:04:14 +08:00
- name: Publish package to TestPyPI
2019-09-15 15:16:54 +08:00
uses: pypa/gh-action-pypi-publish@master
with:
user: __token__
2019-09-15 21:24:35 +08:00
password: ${{ secrets.test_pypi_password }}
2019-09-15 15:16:54 +08:00
repository_url: https://test.pypi.org/legacy/
```
2019-03-28 03:58:36 +08:00
## License
2019-03-28 03:58:36 +08:00
The Dockerfile and associated scripts and documentation in this project
are released under the [BSD 3-clause license](LICENSE.md).
2019-09-25 05:04:57 +08:00
[Creating & using secrets]:
https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets
2019-09-12 20:06:55 +08:00
[has nothing to do with _building package distributions_]:
https://github.com/pypa/gh-action-pypi-publish/issues/11#issuecomment-530480449
2019-09-27 19:37:19 +08:00
[PyPA guide]:
https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/