Skip to content

Commit

Permalink
📝 Outline unsupported scenarios in README
Browse files Browse the repository at this point in the history
webknjaz committed Dec 7, 2024

Verified

This commit was signed with the committer’s verified signature.
reckenrode Randy Eckenrode
1 parent a536fa9 commit 7252a9a
Showing 1 changed file with 75 additions and 0 deletions.
75 changes: 75 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -13,6 +13,10 @@ walkthrough check out the [PyPA guide].
If you have any feedback regarding specific action versions, please leave
comments in the corresponding [per-release announcement discussions].

> [!TIP]
> A limited number of usage scenarios is supported, including the
> [PyPA guide] example. See the [non-goals] for more detail.

## 🌇 `master` branch sunset ❗

@@ -131,6 +135,9 @@ same identity.
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.
They are typically expected to do this in a _separate GitHub Actions
CI/CD job_ running before the one where they call this action and having
restricted privileges.

> [!IMPORTANT]
> Since this GitHub Action is docker-based, it can only
@@ -155,6 +162,72 @@ by putting them into the `dist/` folder prior to running this Action.
> sharing the built dists across stages and jobs. Then, use the `needs`
> setting to order the build, test and publish stages.

The expected environment for running `pypi-publish` is the
GitHub-provided Ubuntu VM. We are running a smoke-test against
`ubuntu-latest` in CI but any currently available numbered versions
should do. We'll consider them supported for as long as GitHub itself
supports them.

Running the action in a job that has a `container:` set is not
supported. It might work for you but you're on your own when it breaks.
If you feel the need to use it, it's likely that you're not following
the recommendation of invoking the build automation in a separate job,
which is considered a security issue (especially, when using [Trusted
Publishing][trusted publisher] that may cause privilege escalation and
would enable the attackers to impersonate the GitHub-backed identity of
the repository through transitive build dependency poisoning). The
solution is to have one job (or multiple, in case of projects with
C-extensions) for building the distribution packages, followed by
another that publishes them.

Self-hosted runners are best effort, provided no other unsupported
things influence them. We are unable to test this in CI and they may
break. This is often the case when using custom runtimes and not the
official GitHub-provided VMs. In general, if you follow the
recommendation of building in a separate job, you shouldn't need to run
this action within a self-hosted runner — it should be possible to
build your dists in a self-hosted runner, save them as a GitHub Actions
artifact in that job, and then invoke the publishing job that would run
within GitHub-provided runners, downloading the artifact with the dists
and publishing them. Such separation is the _recommended_/**supported**
way of handling this scenario.
Our understandng is that Trusted publishing is expected to work on
self-hosted runners. It is backed by OIDC. If it doesn't work, you
should probably ask GitHub if you missed something. We wouldn't be able
to assist here.

Trusted Publishing cannot be tested in CI at the moment, sadly. It is
supported and bugs should be reported but it may take time to sort out
as it often requires cross-project collaboration to debug (sometimes,
problems occur due to changes in PyPI and not in the action).

The only case that is explicitly unsupported at the moment is [Trusted
Publishing][trusted publisher] in reusable workflows. This requires
support on the PyPI side and is being worked on. Please, do not report
bugs related to this case. The current recommendation is to put
everything else you want into a reusable workflow but keep the job
calling `pypi-publish` in a top-level one.

Invoking `pypi-publish` from composite actions is unsupported. It is not
tested. GitHub Runners have limitations and bugs in this case. But more
importantly, this is usually an indication of using it insecurely. When
using [Trusted Publishing][trusted publisher], it is imperative to keep
build machinery invocation in a separate job with restrictive priviliges
as [Trusted Publishing][trusted publisher] itself requires elevated
permissions to make use of OIDC. Our observation is that the users
sometimes create in-project composite actions that invoke building and
publishing in the same job. As such, we don't seek to support such a
dangerous configuration in the first place. The solution is pretty much
the same as with the previous problem — use a separate job with
dedicated and scoped privileges just for publishing; and invoke that
in-project composite action from a different job.

And finally, invoking `pypi-publish` more than once in the same job is
not considered supported. It may work in a limited number of scenarios
but please, don't do this. If you want to publish to several indexes,
build the dists in one job and add several publishing jobs, one per
upload.


## Advanced release management

@@ -294,6 +367,8 @@ https://julienrenaux.fr/2019/12/20/github-actions-security-risk/
[per-release announcement discussions]:
https://github.com/pypa/gh-action-pypi-publish/discussions/categories/announcements

[non-goals]: #Non-goals

[Creating & using secrets]:
https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets
[has nothing to do with _building package distributions_]:

1 comment on commit 7252a9a

@webknjaz
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@woodruffw any thoughts on this?

Please sign in to comment.