diff --git a/docs/automatic-releases/github-actions.rst b/docs/automatic-releases/github-actions.rst index 9f1cffc4e..e5e1af485 100644 --- a/docs/automatic-releases/github-actions.rst +++ b/docs/automatic-releases/github-actions.rst @@ -2,7 +2,7 @@ Setting up python-semantic-release on GitHub Actions ==================================================== Python Semantic Release includes a GitHub Action which runs the ``publish`` -command. +command. The repository is set to `PyPi`. Inputs ------ @@ -14,9 +14,9 @@ Inputs +--------------------------+----------------------------------------------------------------------------------------+ | ``pypi_token`` | See :ref:`env-pypi_token`. | +--------------------------+----------------------------------------------------------------------------------------+ -| ``repository_username`` | See :ref:`env-pypi_username`. | +| ``repository_username`` | See :ref:`env-repository_username`. | +--------------------------+----------------------------------------------------------------------------------------+ -| ``repository_password`` | See :ref:`env-pypi_password`. | +| ``repository_password`` | See :ref:`env-repository_password`. | +--------------------------+----------------------------------------------------------------------------------------+ | ``directory`` | A sub-directory to ``cd`` into before running. Defaults to the root of the repository. | +--------------------------+----------------------------------------------------------------------------------------+ @@ -49,11 +49,11 @@ Example Workflow uses: relekang/python-semantic-release@master with: github_token: ${{ secrets.GITHUB_TOKEN }} - pypi_token: ${{ secrets.PYPI_TOKEN }} + repository_username: __token__ + repository_password: ${{ secrets.PYPI_TOKEN }} -:ref:`env-pypi_token` should be set as a secret on your repository's settings page. -It is also possible to use username and password authentication in a similar -fashion. +:ref:`env-repository_password` should be set as a secret on your repository's settings page. +It is also possible to use username and password authentication in a similar fashion. ``concurrency`` is a `beta feature of GitHub Actions `_ @@ -90,14 +90,16 @@ multiple projects. with: directory: ./project1 github_token: ${{ secrets.GITHUB_TOKEN }} - pypi_token: ${{ secrets.PYPI_TOKEN }} + repository_username: __token__ + repository_password: ${{ secrets.PYPI_TOKEN }} - name: Release Project 2 uses: relekang/python-semantic-release@master with: directory: ./project2 github_token: ${{ secrets.GITHUB_TOKEN }} - pypi_token: ${{ secrets.PYPI_TOKEN }} + repository_username: __token__ + repository_password: ${{ secrets.PYPI_TOKEN }} .. note:: The release notes posted to GitHub will not currently distinguish which diff --git a/docs/automatic-releases/index.rst b/docs/automatic-releases/index.rst index 811420c41..b54eaa0ec 100644 --- a/docs/automatic-releases/index.rst +++ b/docs/automatic-releases/index.rst @@ -69,16 +69,21 @@ Add ``python setup.py publish`` or ``semantic-release publish`` as an after succ preferred Continuous Integration service. Ensure that you have configured the CI so that it can upload to an artifact repository and push to git and it should be ready to roll. -.. _automatic-pypi: +.. _automatic-dist-upload: Configuring distribution upload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to upload to an artifact repository, Python Semantic Release needs credentials to access -the project. You will need to set the environment variable :ref:`env-pypi_token` if you use Pypi, -:ref:`env-repository_username` and :ref:`env-repository_password` otherwise. -Make sure that you mark it as a secret on your CI service so that it is left out -of the build logs. +the project. You will need to set the environment variables :ref:`env-repository_username` and +:ref:`env-repository_password`. Use :ref:`config-repository_url` to set a custom repository url. +As an alternative the repository and/or credentials can be configured using the ``~/.pypirc`` file. +.. warning:: + Make sure to protect any environment variable containing secrets on your CI service. + +.. seealso:: + - `GitLab pypi-repository `_ - GitLab example configuration + - `The .pypirc file `_ - ``~/.pypirc`` documentation .. _automatic-github: @@ -134,3 +139,4 @@ that runs the cronjob has push access to the repository and upload access to an 4. Add cronjob:: /bin/bash -c "cd && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log" + diff --git a/docs/automatic-releases/travis.rst b/docs/automatic-releases/travis.rst index b31f826f4..b26376712 100644 --- a/docs/automatic-releases/travis.rst +++ b/docs/automatic-releases/travis.rst @@ -16,8 +16,9 @@ You will need to set up three environment variables in Travis. An easy way to do is to go to the settings page for your package and add them there. Make sure that the secret toggle is set correct for the ones that are secret. -You will need to set :ref:`env-pypi_token` to a PyPI API token. Furthermore, -you need to set :ref:`env-gh_token` with a personal access token for Github. It will +You will need to set :ref:`env-repository_password` to a PyPI API token and +:ref:`env-repository_username` to `__token__`. +Furthermore, you need to set :ref:`env-gh_token` with a personal access token for Github. It will need either ``repo`` or ``public_repo`` scope depending on whether the repository is private or public. diff --git a/docs/configuration.rst b/docs/configuration.rst index 4292b613d..9dd93e2b4 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -363,21 +363,36 @@ Distributions ``upload_to_pypi`` ------------------ -.. deprecated:: 7.10.0 +.. deprecated:: 7.20.0 Please use :ref:`config-upload_to_repository` instead If set to false the pypi uploading will be disabled. + See :ref:`env-repository` which must also be set for this to work. +Default: `true` + .. _config-upload_to_repository: ``upload_to_repository`` ------------------ If set to false the artifact uploading to repository will be disabled. + See :ref:`env-repository` which must also be set for this to work. Default: `true` +.. _config-upload_to_pypi_glob_patterns: + +``upload_to_pypi_glob_patterns`` +------------------ +.. deprecated:: 7.20.0 + Please use :ref:`config-dist_glob_patterns` instead + +A comma `,` separated list of glob patterns to use when uploading to pypi. + +Default: `*` + .. _config-dist_glob_patterns: ``dist_glob_patterns`` @@ -390,7 +405,21 @@ Default: `*` ``repository`` ------------------ -The repository (package index) to upload to. Should be a section in the ``.pypirc`` file. +The repository (package index) name to upload to. Should be a section in ``~/.pypirc``. +The repositories `pypi` and `testpypi` are preconfigured. + +Default: `pypi` + +.. seealso:: + - `The .pypirc file `_ - ``~/.pypirc`` documentation + +.. _config-repository_url: + +``repository_url`` +----------------- +The repository (package index) URL to upload the package to. + +See :ref:`automatic-dist-upload` for more about uploads to custom repositories. .. _config-upload_to_release: @@ -428,14 +457,6 @@ files should be placed manually in the directory configured in Default: ``python setup.py sdist bdist_wheel`` -.. _config-repository_url: - -``repository_url`` ------------------ -The repository (package index) URL to upload the package to. - -Default: ``pypi`` - HVCS ==== diff --git a/docs/envvars.rst b/docs/envvars.rst index 9809fb007..2644ff5d0 100644 --- a/docs/envvars.rst +++ b/docs/envvars.rst @@ -82,7 +82,7 @@ and click on *Personal access token*. A personal access token from GitLab. This is used for authenticating when pushing tags, publishing releases etc. -.. _env-repository +.. _env-repository: Artifact Repository Authentication ================================== @@ -91,40 +91,25 @@ Artifact Repository Authentication ``PYPI_TOKEN`` -------------- -Set an API token for publishing to https://pypi.org/. Information on how to -obtain a token is given `here `_. +.. deprecated:: 7.20.0 + Please use :ref:`env-repository_password` instead -See :ref:`automatic-pypi` for more about PyPI uploads. - -.. note:: - If :ref:`env-pypi_password`, :ref:`env-pypi_username`, and :ref:`env-pypi_token` are not specified credentials from ``$HOME/.pypirc`` will be used. +Set an API token for publishing to https://pypi.org/. .. _env-pypi_password: ``PYPI_PASSWORD`` ----------------- -.. deprecated:: 7.10.0 - Please use :ref:`env-repository_username` instead - -Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/. - -.. warning:: - You should use :ref:`env-pypi_token` instead of username and password - authentication for the following reasons: +.. deprecated:: 7.20.0 + Please use :ref:`env-repository_password` instead - - It is `strongly recommended by PyPI `_. - - Tokens can be given access to only a single project, which reduces the - possible damage if it is compromised. - - You can change your password without having to update it in CI settings. - - If your PyPI username is the same as your GitHub and you have it set - as a secret in a CI service, they will likely scrub it from the build - output. This can break things, for example repository links. +Used together with :ref:`env-pypi_username` when publishing to https://pypi.org/. .. _env-pypi_username: ``PYPI_USERNAME`` ----------------- -.. deprecated:: 7.10.0 +.. deprecated:: 7.20.0 Please use :ref:`env-repository_username` instead Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/. @@ -135,8 +120,26 @@ Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/ ----------------------- Used together with :ref:`env-repository_password` when publishing artifact. +.. note:: + If you use token authentication with `pypi` set this to `__token__` + .. _env-repository_password: ``REPOSITORY_PASSWORD`` ----------------------- Used together with :ref:`env-repository_username` when publishing artifact. +Also used for token when using token authentication. + +.. warning:: + You should use token authentication instead of username and password + authentication for the following reasons: + + - It is `strongly recommended by PyPI `_. + - Tokens can be given access to only a single project, which reduces the + possible damage if it is compromised. + - You can change your password without having to update it in CI settings. + - If your PyPI username is the same as your GitHub and you have it set + as a secret in a CI service, they will likely scrub it from the build + output. This can break things, for example repository links. + + - Find more information on `how to obtain a token `_. diff --git a/docs/index.rst b/docs/index.rst index b76fd287d..d67de411d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -79,13 +79,19 @@ release notes and new versions to GitHub / GitLab: - :ref:`env-gh_token` - GitHub personal access token. - :ref:`env-gl_token` - GitLab personal access token. -Releasing on PyPI +Distributing release on PyPI or custom repository ----------------- -Unless you disable :ref:`config-upload_to_pypi`, Python Semantic Release will -publish new versions on PyPI. This requires you to obtain an API token -`here `_ and store it in the environment -variable :ref:`env-pypi_token`. +Unless you disable :ref:`config-upload_to_repository` (or :ref:`config-upload_to_pypi`), +Python Semantic Release will publish new versions to `Pypi`. Customization is supported using a +``~/.pypirc`` file or config setting and environment variables for username and password/token or a +combination of both. +Publishing is done using `twine `_. + +- :ref:`config-repository` - use repository and/or credentials from ``~/.pypirc`` file +- :ref:`config-repository_url` - set custom repository url +- :ref:`env-repository` - provide credentials using environment variables +- :ref:`automatic-dist-upload` - configuring CI distribution upload .. include:: commands.rst