Merge branch 'unstable/v1' into ww/reusable-warn

Author: woodruffw

.github/FUNDING.yml

@@ -13,4 +13,10 @@ ko_fi: webknjaz
 
 liberapay: webknjaz
 
+open_collective: webknjaz
+
+# patreon: webknjaz  # not in use because of the ties with ruscism
+
+thanks_dev: u/gh/webknjaz
+
 ...

.github/workflows/build-and-push-docker-image.yml

@@ -16,11 +16,28 @@ on:   # yamllint disable-line rule:truthy
 jobs:
   smoke-test:
     uses: ./.github/workflows/reusable-smoke-test.yml
+
+  check:  # This job does nothing and is only used for the branch protection
+    if: always()
+
+    needs:
+    - smoke-test
+
+    runs-on: ubuntu-latest
+
+    timeout-minutes: 1
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}
+
   build-and-push:
     if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     needs:
-    - smoke-test
+    - check
     timeout-minutes: 10
     steps:
     - uses: actions/checkout@v4

.github/workflows/reusable-smoke-test.yml

@@ -26,6 +26,19 @@ env:
     PYTEST_THEME_MODE
 
 jobs:
+  legit-pr:
+
+    runs-on: ubuntu-latest
+
+    timeout-minutes: 1
+
+    steps:
+    - name: Fail on PRs against illegal branches (`${{ github.base_ref }}`)
+      if: >-
+        github.event_name == 'pull_request'
+        && github.base_ref != github.event.repository.default_branch
+      run: exit 1
+
   fail-fast:
 
     strategy:
@@ -53,7 +66,13 @@ jobs:
 
   smoke-test:
 
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os:
+        - ubuntu-24.04
+        - ubuntu-22.04
+
+    runs-on: ${{ matrix.os }}
 
     services:
       devpi:
@@ -86,7 +105,7 @@ jobs:
         CONTENTS: |
           [build-system]
           requires = [
-            "setuptools == 65.6.3",
+            "setuptools == 75.8.0",
           ]
           build-backend = "setuptools.build_meta"
 
@@ -96,8 +115,31 @@ jobs:
           readme = "README.md"
     - name: Build the stub package sdist and wheel distributions
       run: python3 -m build
+    - name: Create the Rust package directory
+      run: mkdir -pv rust-example
+    - name: Initialize a Rust project
+      run: cargo init
+      working-directory: rust-example
+    - name: Populate the Rust package `pyproject.toml`
+      run: echo "$CONTENTS" > pyproject.toml
+      env:
+        CONTENTS: |
+          [build-system]
+          requires = [
+            "maturin ~=1.0",
+          ]
+          build-backend = "maturin"
+      working-directory: rust-example
+    - name: Build the stub package sdist and wheel distributions
+      run: python3 -m build -o ../dist/
+      working-directory: rust-example
     - name: Register the stub package in devpi
-      run: twine register dist/*.tar.gz
+      run: |
+        for dist in dist/*.tar.gz
+        do
+          echo "Registering ${dist}..."
+          twine register "${dist}"
+        done
       env:
         TWINE_USERNAME: ${{ env.devpi-username }}
         TWINE_PASSWORD: ${{ env.devpi-password }}

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
   - id: add-trailing-comma
 
 - repo: https://github.com/PyCQA/isort.git
-  rev: 5.13.2
+  rev: 6.0.0
   hooks:
   - id: isort
     args:
@@ -22,7 +22,7 @@ repos:
   - id: remove-tabs
 
 - repo: https://github.com/python-jsonschema/check-jsonschema.git
-  rev: 0.29.2
+  rev: 0.31.1
   hooks:
   - id: check-github-actions
   - id: check-github-workflows
@@ -37,7 +37,7 @@ repos:
   - id: check-readthedocs
 
 - repo: https://github.com/pre-commit/pre-commit-hooks.git
-  rev: v4.6.0
+  rev: v5.0.0
   hooks:
   # Side-effects:
   - id: end-of-file-fixer
@@ -62,7 +62,7 @@ repos:
     language_version: python3
 
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.2.6
+  rev: v2.4.1
   hooks:
   - id: codespell
 
@@ -78,7 +78,7 @@ repos:
     - --strict
 
 - repo: https://github.com/PyCQA/flake8.git
-  rev: 7.0.0
+  rev: 7.1.1
   hooks:
   - id: flake8
     args:
@@ -97,6 +97,7 @@ repos:
       WPS111,
       WPS202,
       WPS305,
+      WPS318,
       WPS326,
       WPS332,
       WPS347,
@@ -109,14 +110,14 @@ repos:
       WPS440,
       WPS441,
       WPS453,
+    - --max-module-members=8  # WPS202
     additional_dependencies:
-    - flake8-2020 ~= 1.7.0
-    - flake8-pytest-style ~= 1.6.0
-    - wemake-python-styleguide ~= 0.19.0
-    language_version: python3.11  # flake8-commas doesn't work w/ Python 3.12
+    - flake8-2020 ~= 1.8.1
+    - flake8-pytest-style ~= 2.1.0
+    - wemake-python-styleguide ~= 1.0.0
 
 - repo: https://github.com/PyCQA/pylint.git
-  rev: v3.3.0
+  rev: v3.3.4
   hooks:
   - id: pylint
     args:

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.12-slim
+FROM python:3.13-slim
 
 LABEL "maintainer" "Sviatoslav Sydorenko <wk+pypa@sydorenko.org.ua>"
 LABEL "repository" "https://github.com/pypa/gh-action-pypi-publish"
@@ -12,7 +12,7 @@ ENV PIP_NO_CACHE_DIR 1
 ENV PIP_ROOT_USER_ACTION ignore
 
 ENV PATH "/root/.local/bin:${PATH}"
-ENV PYTHONPATH "/root/.local/lib/python3.12/site-packages"
+ENV PYTHONPATH "/root/.local/lib/python3.13/site-packages"
 
 COPY requirements requirements
 RUN \

README.md

@@ -1,7 +1,9 @@
 [![SWUbanner]][SWUdocs]
 
+![PyPA badge]
 [![🧪 GitHub Actions CI/CD workflow tests badge]][GHA workflow runs list]
 [![pre-commit.ci status badge]][pre-commit.ci results page]
+[![GH Sponsors badge]][GH Sponsors URL]
 
 # PyPI publish GitHub Action
 
@@ -13,6 +15,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 +137,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 +164,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 privileges
+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
 
@@ -277,6 +352,8 @@ on supported platforms (like GitHub).
 The Dockerfile and associated scripts and documentation in this project
 are released under the [BSD 3-clause license](LICENSE.md).
 
+[PyPA badge]:
+https://img.shields.io/badge/project-yellow?label=PyPA&labelColor=ffd242&color=3775a9
 
 [🧪 GitHub Actions CI/CD workflow tests badge]:
 https://github.com/pypa/gh-action-pypi-publish/actions/workflows/build-and-push-docker-image.yml/badge.svg?branch=unstable%2Fv1&event=push
@@ -288,12 +365,24 @@ https://results.pre-commit.ci/latest/github/pypa/gh-action-pypi-publish/unstable
 [pre-commit.ci status badge]:
 https://results.pre-commit.ci/badge/github/pypa/gh-action-pypi-publish/unstable/v1.svg
 
+[docs badge]:
+https://img.shields.io/badge/guide-gray?logo=readthedocs&label=PyPUG&color=white
+[PyPUG guide]:
+https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+
+[GH Sponsors badge]:
+https://img.shields.io/badge/%40webknjaz-transparent?logo=githubsponsors&logoColor=%23EA4AAA&label=Sponsor&color=2a313c
+[GH Sponsors URL]:
+https://github.com/sponsors/webknjaz
+
 [use a full Git commit SHA]:
 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_]: