Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a guide about publishing dists via GH Actions #647

Merged
Merged
Changes from 1 commit
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -29,3 +29,4 @@ introduction to packaging, see :doc:`/tutorials/index`.
migrating-to-pypi-org
using-testpypi
making-a-pypi-friendly-readme
publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
@@ -0,0 +1,168 @@
Publishing Package Distribution 📦 Releases Using GitHub Actions CI/CD Workflows 🤖
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Other guides (well, the two I checked :) use sentence case for titles:

Suggested change
Publishing Package Distribution 📦 Releases Using GitHub Actions CI/CD Workflows 🤖
Publishing package distribution 📦 releases using GitHub Actions CI/CD workflows 🤖

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

Are you sure? I've title-cased this because I saw it in some other guides. Let me check...

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

Alright, you're correct. I'm probably confused about something else I saw.

This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@pfmoore

pfmoore Sep 16, 2019

Member

Minor style nit - I don't think we normally use emoji in titles, and in this particular case, I think it makes the title less readable. Maybe stick to simple text?

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

I think it's a matter of taste. For me, emojis make things more lively. As a side-effect — I often use them in places to also test Unicode-related issues.

I feel like the robot face makes it more relatable, pointing out that it's a kind of automation.
As for the package, it may be redundant given that the whole web-site is about packaging.

Personally, I'd like to keep emojis but if you have a rather strong opinion, I'll be happy to drop them.
WDYT?

This comment has been minimized.

Copy link
@pradyunsg

pradyunsg Sep 16, 2019

Member

This is a nit so I won't say anything be saying much here -- just noting my preferences once.

I prefer if we drop emoji from the title. I'm 100% for having them in the prose/content of the guide.

===================================================================================

`GitHub Actions CI/CD`_ allow you to run a series of commands
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 18, 2019

Contributor
Suggested change
`GitHub Actions CI/CD`_ allow you to run a series of commands
`GitHub Actions CI/CD`_ allows you to run a series of commands
whenever an event occurs in the GitHub Platform. One of the
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Briefer:

Suggested change
whenever an event occurs in the GitHub Platform. One of the
whenever an event occurs on GitHub. One

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

I feel like just "GitHub", in most of the human minds, refers to something that's viewable on the surface, like the UI-visible things. I think that it's a bit inaccurate because there's events that many people almost never hear, like deployment, or schedule, or event custom events that Actions support too.

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Makes sense. How about "on the GitHub platform"?

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

Sounds good.

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member
Suggested change
whenever an event occurs in the GitHub Platform. One of the
whenever an event occurs on the GitHub platform. One
popular choices is having a workflow that's triggered by a
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
popular choices is having a workflow that's triggered by a
popular choice is having a workflow that's triggered by a
``push`` event.
This guide will show you how to publish a Python distribution
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
This guide will show you how to publish a Python distribution
This guide shows you how to publish a Python distribution
package whenever a tagged commit is pushed.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
package whenever a tagged commit is pushed.
whenever a tagged commit is pushed.

.. attention::

This guide *assumes* that you already have a project that
you know how to build dists for and *it lives on GitHub*.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
you know how to build dists for and *it lives on GitHub*.
you know how to build distributions for and *it lives on GitHub*.

.. warning::

At the time of writing this guide, `GitHub Actions CI/CD`_
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
At the time of writing this guide, `GitHub Actions CI/CD`_
At the time of writing, `GitHub Actions CI/CD`_
is still in public beta. If you don't have it enabled,
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
is still in public beta. If you don't have it enabled,
is in public beta. If you don't have it enabled,
you should join the waitlist in order to gain the access.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
you should join the waitlist in order to gain the access.
you should join the waitlist to gain access.

And add link to where to join waitlist? https://github.com/features/actions/signup/


N.B. It is known that GitHub is going to make Actions
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
N.B. It is known that GitHub is going to make Actions
GitHub Actions will be generally available on November 13th, 2019.
publicly available on the Nov 13th, 2019.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
publicly available on the Nov 13th, 2019.


Saving credentials on GitHub
----------------------------

In this guide, we'll demonstrate uploading to both production
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
In this guide, we'll demonstrate uploading to both production
In this guide, we'll demonstrate uploading to both
PyPI and Test PyPI meaning that we'll have two separate sets
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
PyPI and Test PyPI meaning that we'll have two separate sets
PyPI and TestPyPI, meaning that we'll have two separate sets
of creds. And we'll need to save them in GitHub repo settings.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
of creds. And we'll need to save them in GitHub repo settings.
of creds. And we'll need to save them in the GitHub repo settings.

Let's begin! 🚀

1. Go to https://pypi.org/manage/account/#api-tokens and

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Maybe put the Test PyPI instructions before production PyPI?

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

I think users usually have an account on prod, but rarely on test...

create a new `API token`_. If you have the project on PyPI
already, please limit the token scope to just that project.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

For brevity:

Suggested change
already, please limit the token scope to just that project.
already, limit the token scope to just that project.
You can call it smth like
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
You can call it smth like
You can call it something like
``GitHub Actions CI/CD — project-org/project-repo``
in order for it to be easily distinguishable in the token
list.
**Don't close the page just yet — you won't see that token
again.**
2. In a separate browser tab or window, go to the ``Settings``
tab of your target repository and then click on `Secrets`_
in the left sidebar.
3. Create a new secret called ``pypi_password`` and copy-paste
the token from the fist step.
4. Now, go to https://test.pypi.org/manage/account/#api-tokens
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member

Maybe add a note here that you might need to create a TestPyPI account? The fact that PyPI accounts don't work on TestPyPI often confuses users.

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 19, 2019

Author Member

Fair enough, I'll add this info.

and repeat the steps. Save that Test PyPI token on GitHub
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
and repeat the steps. Save that Test PyPI token on GitHub
and repeat the steps. Save that TestPyPI token on GitHub
as ``test_pypi_password``.

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
as ``test_pypi_password``.
as ``testpypi_password``.

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 19, 2019

Author Member

I think that it's better readable to maintain snake_case here.

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 19, 2019

Contributor

Is testpypi_password the snake_case version of TestPyPI (no space)?

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 19, 2019

Author Member

TestPyPI is CamelCase version and it's clearly visible that test is a separate word, even though it's spelled together in the capitalized version. So I consider test_pypi_password a proper snake_case version.



Creating a workflow definition
------------------------------

GitHub CI/CD Workflows are declared in YAML files stored under
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
GitHub CI/CD Workflows are declared in YAML files stored under
GitHub CI/CD workflows are declared in YAML files stored under
``.github/`` of your repository.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

I've only seen them in .github/workflows/. Can they go in .github/? Should they be standardised in .github/workflows/?

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

Ah, it's my mistake.

Suggested change
``.github/`` of your repository.
``.github/workflows/`` of your repository.

Start it with a meaningful name and define the even that
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Typo

Suggested change
Start it with a meaningful name and define the even that
Start it with a meaningful name and define the event that
should make GitHub run this workflow:

.. code-block:: yaml
name: Publish Python 🐛 distribution package 📦 to PyPIs
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

🐛 is a bug, not a snake :)

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member
Suggested change
name: Publish Python 🐛 distribution package 📦 to PyPIs
name: Publish Python 🐍 distribution package 📦 to PyPIs
on: push
Defining a workflow job environment
-----------------------------------

Now, let's add initial setup for our job. It's a process that
will execute commands that we'll define later.
In this guide, we'll choose to use Ubuntu 18.04:
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 18, 2019

Contributor
Suggested change
In this guide, we'll choose to use Ubuntu 18.04:
In this guide, we'll use Ubuntu 18.04:

.. code-block:: yaml
build-n-publish:
name: Build and publish Python 🐛 dist 📦 to PyPIs
runs-on: ubuntu-18.04
Checking out the project and building dists
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
Checking out the project and building dists
Checking out the project and building distributions
-------------------------------------------

Then, add the following under the ``build-n-publish`` section:

.. code-block:: yaml
steps:
- uses: actions/checkout@master
- name: Set up Python 3.7
uses: actions/setup-python@v1
with:
version: 3.7
This will download your repository into the CI runner and then
install and activate Python 3.7.

And now we can build dists from source. In this example, we'll
use ``pep517`` package, *assuming that your project has a ``pyproject.toml`` properly set up (see :pep:`517`/:pep:`518`)*.

.. tip::

You can use any other method for building dists as long as
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
You can use any other method for building dists as long as
You can use any other method for building distributions as long as
it produces ready-to-upload artifacts saved into ``dist/``
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
it produces ready-to-upload artifacts saved into ``dist/``
it produces ready-to-upload artifacts saved into the ``dist/``
folder.

So add this to the steps list:

.. code-block:: yaml
- name: Install pep517
run: >-
python -m
pip install
pep517
--user
- name: Build a binary wheel and a source tarball
run: >-
python -m
pep517.build
--source
--binary
--out-dir dist/
.
Publishing dist to Test PyPI and production PyPI
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
Publishing dist to Test PyPI and production PyPI
Publishing the distribution to PyPI and TestPyPI
------------------------------------------------

Finally, add the following steps in the end:
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
Finally, add the following steps in the end:
Finally, add the following steps at the end:

.. code-block:: yaml
- name: Publish 📦 to Test PyPI
uses: pypa/gh-action-pypi-publish@master
with:
password: ${{ secrets.test_pypi_password }}
repository_url: https://test.pypi.org/legacy/
- name: Publish 📦 to production PyPI
if: startsWith(github.event.ref, 'refs/tags')
uses: pypa/gh-action-pypi-publish@master
with:
password: ${{ secrets.pypi_password }}
These two steps use `pypa/gh-action-pypi-publish`_ GitHub
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
These two steps use `pypa/gh-action-pypi-publish`_ GitHub
These two steps use the `pypa/gh-action-pypi-publish`_ GitHub
Action: the first one uploads contents of the `dist/` folder
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Remember double backticks for code in RST

Suggested change
Action: the first one uploads contents of the `dist/` folder
Action: the first one uploads contents of the ``dist/`` folder

This comment has been minimized.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

Right! I missed this place, thanks!

This comment was marked as resolved.

Copy link
@webknjaz

webknjaz Sep 16, 2019

Author Member

@hugovk could you please edit your suggestion and shift the left backtick to the right? The current one has a space between opening backticks making it invalid.

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor

Oops, fixed!

into Test PyPI unconditionally and the second does that to
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
into Test PyPI unconditionally and the second does that to
into TestPyPI unconditionally and the second does that to
production PyPI but only if the current commit is tagged.
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
production PyPI but only if the current commit is tagged.
PyPI, but only if the current commit is tagged.


That's all, folks!
------------------

Now, whenever you push a tagged commit to your Git repo remote
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
Now, whenever you push a tagged commit to your Git repo remote
Now, whenever you push a tagged commit to your Git repository remote
on GitHub, this workflow will publish it to PyPI.
And it'll publish any push to Test PyPI which is useful for
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@di

di Sep 19, 2019

Member
Suggested change
And it'll publish any push to Test PyPI which is useful for
And it'll publish any push to TestPyPI which is useful for
providing test builds to your alpha users as well as making
sure that your release pipeline keeps being healthy!
This conversation was marked as resolved by webknjaz

This comment has been minimized.

Copy link
@hugovk

hugovk Sep 16, 2019

Contributor
Suggested change
sure that your release pipeline keeps being healthy!
sure that your release pipeline remains healthy!


.. _API token: https://pypi.org/help/#apitoken
.. _GitHub Actions CI/CD: https://github.com/features/actions
.. _pypa/gh-action-pypi-publish:
.. _Secrets:
https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.