[sept 17 merge] review: trusted publishing tutorial #561

lwasser · 2025-07-22T21:53:29Z

This adds the trusted publishing tutorial as a pr so we can spend time reviewing it. Relates to #253 submitted by @mihaimaruseac

let's leave this page open for a few weeks to allow for time to review!

Midnighter

I just read the tutorial online and it is well structured, has good language, sane content, and I didn't miss anything.

👍🏼 from me.

mihaimaruseac

LGTM (cannot approve/request changes, but it looks good to me)

ucodery

This guide is GREAT!

tutorials/trusted-publishing.md

ucodery · 2025-07-23T19:56:55Z

tutorials/trusted-publishing.md

+chain attack due to GitHub Actions is the recent `tj-actions/changed-files` 
+attack[^changed-files-supply-chain-attack]). Enabling Dependabot[^dependabot] in 
+the repository will ensure that you always get a PR to keep the actions up to 
+date. 


Even for those not concerned about security, actions can be pinned to a version so that when a breaking change is introduced, your workflows do not break and you can upgrade when you have time (actions/checkout@v4).
Maybe that is too TMO for this guide. But also, I worry about posting hash-commits in a guide that will likely be copy-pasted.

Should be put it in a footnote and then have all examples use the tags instead?

SO i just came here to comment on this issue. If someone copies/pastes this workflow, it will be dated. It is already dated!!

Is there some clever way to set up Dependabot for this repo to keep things updated here?

Alternatively, we could update https://github.com/pyOpenSci/pyosPackage with this workflow too.
We could merge this and open an issue about how we maintain actions.

Update: I figured out how to setup dependabot to update a ci action in a subdirectory. This has been merged into main and I moved the entire workflow into a ci action here.

https://github.com/pyOpenSci/python-package-guide/blob/main/examples/pure-hatch/.github/workflows/release.yml

The hatch install action I don't think that exists (or I can't find it, so I added a commit to this PR that installs hatch with pip. ✨

tutorials/trusted-publishing.md

sneakers-the-rat

Super good, love it. The one thing I think would make it even better is to lead with an example scenario to motivate the reason for having trusted publishers in the first place. I think the idea of supply chain vulns would probably not be familiar to tutorial readers, so a scenario like "so you've written a very cool thing and other people are using it and depending on it. So far you've been just publishing from your laptop , but one day you accidentally copy paste your password into bluesky (or whatever lol) and someone swipes it before you delete it! Now they are using your cool thing to steal other people's credit cards, that's not good! We can make things easier for ourselves as well as avoiding a certain category of attacks by..."

Just an example, hopefully u know what I'm saying. Bonus points for using a real example too :)

Good addition!!! I'll probs add an appendix for codeberg which doesn't have trusted publishing if we don't already have something for that already after this is merged.

sneakers-the-rat · 2025-07-23T22:29:46Z

tutorials/trusted-publishing.md

+To get started, create a file named `release.yaml` under the `.github/workflows` 
+directory of your project. 
+
+:::{admonition} Naming the workflow 


Maybe as a footnote or collapsed admonition? Good info for newbies, a little bit distracting from flow of prose. Not strong opinion.

Footnote seems good to me, thank you!

I like this here because I can see this being a question that a beginner would have!! Let's try it out, and we can add footnotes later if we decide they are more appropriate!

tutorials/trusted-publishing.md

sneakers-the-rat · 2025-07-23T22:59:22Z

tutorials/trusted-publishing.md

+Once you fill in this form and click "Add" the publisher is configured and can 
+be used to publish new releases of your package. 
+
+:::{admonition} Fully hardened GitHub Actions release workflow 


This might be pedantic, but I'm always a bit wary to give the impressions to newbies that security can be "completed" because it might lead to thinking "I'm fully secure, so whatever I do is fine now!"

What do you think about adding a statement that - we also suggest setting up Dependabot at the bottom. That would be the next natural step in consistently maintaining these actions.

sneakers-the-rat · 2025-07-23T23:01:14Z

tutorials/trusted-publishing.md

+:::{admonition} Fully hardened GitHub Actions release workflow 
+
+For better security it is recommended to also control the permissions of the 
+GitHub token used within each job of the workflow. The permissions should be 


A little example might be helpful: "for example, if one of your dependencies was taken over by a malicious actor and embedded code to steal environment variables... since the only code running in the publish step is the trusted publisher action..."

sneakers-the-rat · 2025-07-23T23:02:25Z

tutorials/trusted-publishing.md

+
+## You have enabled trusted publishing for your project 
+
+Congratulations. You have now configured your project to do secure releases when a new version is being tagged on GitHub. The workflow we have configured builds the package from the exact version of code that we are tagging. This provides a guarantee for your users that the package we have released does exactly what the code states it does -- there is no potential for supply chain related vulnerabilities arising from our package! If you have a package that is ready for real-world use on the real PyPI, then you can follow the same steps to publish it securely. 


still some possibility! But we have reduced the possibility and made it convenient to publish.

mathematicalmichael

this is fantastic.

does the packaging here presume automatic versioning of the package based on tag (or is it useful to remind the user to "stage" their pyproject.toml for publication by specifying the release version and then creating a release to match it?)

tutorials/trusted-publishing.md

mihaimaruseac · 2025-07-24T21:16:23Z

So far you've been just publishing from your laptop , but one day you accidentally copy paste your password into bluesky (or whatever lol) and someone swipes it before you delete it! Now they are using your cool thing to steal other people's credit cards, that's not good! We can make things easier for ourselves as well as avoiding a certain category of attacks by..."

Just an example, hopefully u know what I'm saying. Bonus points for using a real example too :)

This is cool example and I think a real world scenario just occurred recently. I'll investigate more before linking to it.

lwasser · 2025-09-15T19:56:48Z

@all-contributors please add @mathematicalmichael for review

allcontributors · 2025-09-15T19:56:59Z

@lwasser

I've put up a pull request to add @mathematicalmichael! 🎉

lwasser · 2025-09-15T19:58:11Z

@all-contributors please add @mihaimaruseac for review

allcontributors · 2025-09-15T19:58:15Z

@lwasser

@mihaimaruseac already contributed before to review

tutorials/trusted-publishing.md

ucodery · 2025-09-15T21:39:08Z

tutorials/trusted-publishing.md

+A GitHub Actions *workflow* file can contain multiple *jobs* that run independently, each of which can have multiple *steps.*
+When triggered, the GitHub Actions runs all the jobs in a workflow[^conditionally]. We have to configure at 
+
+[^conditionally]: Jobs and steps can also have [conditional logic](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idif) that makes them only run in certain circumstances.
 least one job in the workflow file. 


this sentence got cut in half

Good catch. I am looking locally, and this section actually is odd because the first paragraph ends in an incomplete sentence, and then this section doesn't render at all.

Co-authored-by: Michael Pilosov, PhD <[email protected]> Co-authored-by: Jeremiah Paige <[email protected]> Co-authored-by: Mihai Maruseac <[email protected]> Co-authored-by: Jonny Saunders <[email protected]>

Co-authored-by: Jeremiah Paige <[email protected]>

lwasser · 2025-09-16T20:40:35Z

tutorials/trusted-publishing.md

+    runs-on: ubuntu-latest 
+    steps: 
+    - uses: actions/checkout 
+    - uses: pypa/hatch 


@ucodery or anyone who knows!!! does this action step exist? I can't find it, and I've installed it manually when using it.

I haven't used that as an action before, so I don't know. However, a search for such an action seems to reveal nothing.

Thank you!! It's not just me. Dependabot also did not update it. I don't think it exists!! I usually install Hatch using pip or pipx, so I'll update it as well.

I have to say that your idea of Literal Includes is fixing a lot of things in this PR!! So thank you for being months and months and months ahead of where my brain was and for adding those example packages to this repo!!

…enSci#577)

Bumps the actions group in /examples/pure-hatch/.github/workflows with 3 updates: [actions/checkout](https://github.com/actions/checkout), [actions/download-artifact](https://github.com/actions/download-artifact) and [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish). Updates `actions/checkout` from 4.2.2 to 5.0.0 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@11bd719...08c6903) Updates `actions/download-artifact` from 4.3.0 to 5.0.0 - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](actions/download-artifact@d3f86a1...634f93c) Updates `pypa/gh-action-pypi-publish` from 1.12.4 to 1.13.0 - [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases) - [Commits](pypa/gh-action-pypi-publish@76f52bc...ed0c539) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 5.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions - dependency-name: actions/download-artifact dependency-version: 5.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions - dependency-name: pypa/gh-action-pypi-publish dependency-version: 1.13.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

lwasser · 2025-09-17T00:13:03Z

.github/dependabot.yml

+    commit-message:
+      prefix: "chore"
+  - package-ecosystem: "github-actions"
+    directory: "examples/pure-hatch/.github/workflows"


This updates the github action so dep versions are always current!

lwasser · 2025-09-17T00:13:18Z

examples/pure-hatch/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release


This is the new action that the entire tutorial pulls from to ensure current information

lwasser · 2025-09-17T00:13:40Z

examples/pure-hatch/.github/workflows/release.yml

+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: "3.12" # Select the version that you want to build your package on
+      - name: Upgrade pip, install Hatch, and check Hatch version


I believe that we have to install hatch manually here as i can't find a hatch specific action.

lwasser changed the title ~~review: trusted publishing tutorial~~ [aug 8 merge] review: trusted publishing tutorial Jul 22, 2025

lwasser added the 🚀 ready-for-review label Jul 22, 2025

Midnighter approved these changes Jul 22, 2025

View reviewed changes

mihaimaruseac reviewed Jul 23, 2025

View reviewed changes

ucodery reviewed Jul 23, 2025

View reviewed changes

sneakers-the-rat approved these changes Jul 23, 2025

View reviewed changes

mathematicalmichael reviewed Jul 24, 2025

View reviewed changes

tutorials/trusted-publishing.md Outdated Show resolved Hide resolved

tutorials/trusted-publishing.md Outdated Show resolved Hide resolved

lwasser mentioned this pull request Sep 10, 2025

docs(ci): setup circle ci for site preview from GitHub all-contributors/all-contributors#913

Open

allcontributors bot mentioned this pull request Sep 15, 2025

docs: add mathematicalmichael as a contributor for review #576

Merged

ucodery reviewed Sep 15, 2025

View reviewed changes

lwasser and others added 2 commits September 16, 2025 14:19

review: trusted publishing tutorial

722c854

Apply suggestions from code review

d74838e

Co-authored-by: Michael Pilosov, PhD <[email protected]> Co-authored-by: Jeremiah Paige <[email protected]> Co-authored-by: Mihai Maruseac <[email protected]> Co-authored-by: Jonny Saunders <[email protected]>

lwasser force-pushed the tutorial-trusted-publishing branch from 8c74bf6 to d74838e Compare September 16, 2025 20:19

Apply suggestions from code review

920d3b6

Co-authored-by: Jeremiah Paige <[email protected]>

lwasser commented Sep 16, 2025

View reviewed changes

docs(review): updates from review

29013ee

lwasser mentioned this pull request Sep 16, 2025

chore(deps): Update dependabot configuration for GitHub Actions #577

Merged

lwasser and others added 4 commits September 16, 2025 16:27

chore(deps): Update dependabot configuration for GitHub Actions (pyOp…

10ef74c

…enSci#577)

Fix: includes

d7e8774

feat: literal includes for the action

f1f92bc

lwasser changed the title ~~[aug 8 merge] review: trusted publishing tutorial~~ [sept 17 merge] review: trusted publishing tutorial Sep 16, 2025

docs: fix workflow

c9abedd

lwasser commented Sep 17, 2025

View reviewed changes

lwasser added 2 commits September 16, 2025 18:49

chore: fix errors from docs-test

7429c12

Merge branch 'main' into tutorial-trusted-publishing

cfe7167


		## You have enabled trusted publishing for your project

		Congratulations. You have now configured your project to do secure releases when a new version is being tagged on GitHub. The workflow we have configured builds the package from the exact version of code that we are tagging. This provides a guarantee for your users that the package we have released does exactly what the code states it does -- there is no potential for supply chain related vulnerabilities arising from our package! If you have a package that is ready for real-world use on the real PyPI, then you can follow the same steps to publish it securely.

[sept 17 merge] review: trusted publishing tutorial #561

Are you sure you want to change the base?

[sept 17 merge] review: trusted publishing tutorial #561

Conversation

lwasser commented Jul 22, 2025

Uh oh!

Midnighter left a comment

Choose a reason for hiding this comment

Uh oh!

mihaimaruseac left a comment

Choose a reason for hiding this comment

Uh oh!

ucodery left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sneakers-the-rat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mathematicalmichael left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mihaimaruseac commented Jul 24, 2025

Uh oh!

lwasser commented Sep 15, 2025

Uh oh!

allcontributors bot commented Sep 15, 2025

Uh oh!

lwasser commented Sep 15, 2025

Uh oh!

allcontributors bot commented Sep 15, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment