Claude Skill

pypi-ops

Publish Python packages to PyPI via OIDC Trusted Publishing (PEP 740 attestations, gh-action-pypi-publish) instead of stored tokens. Use for: invalid-publisher errors, pending-publisher 404s, uv publish/twine, TestPyPI, environment approval gates, and rotating/auditing publish to

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_pypi-ops-fa93328.zip · 26 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/pypi-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

PyPI Operations

Publish Python packages to PyPI on the 2026 best-practice path: OIDC Trusted Publishing with signed PEP 740 attestations, no long-lived token to leak. This skill owns the publish layer (the registry handshake, the first-publish gotchas, the recovery playbook). General GitHub Actions syntax is ci-cd-ops; the install-side worm defense is supply-chain-defense; gh/release-page mechanics are github-ops.

Where this fits — the release pipeline

A release spans several skills; pypi-ops owns the registry step. Chain them:

  1. Vet dependencies before cutting a release — supply-chain-defense (cooldown + behavioural scan). The build runs dependency code before it touches your publish credential, so a poisoned build dep can steal the token.
  2. Preflight — scripts/publish-preflight.sh --build . (this skill).
  3. Bump → tag → push — git-ops (its push-preflight scans for secrets / forbidden files before the tag goes up).
  4. CI publishes via OIDC — this skill's assets/publish.yml; you approve at the pypi environment gate.
  5. Release page (optional, GitHub) — github-ops, human-reviewed notes.

The one decision: OIDC vs API token

Default to OIDC Trusted Publishing. Reach for a token only when OIDC is impossible (publishing from a non-supported CI, or a one-off local push).

Trusted Publishing (OIDC) ← default API token
Secret stored None — short-lived OIDC token minted per run Long-lived pypi-… token in a secret
Leak/phish blast radius None to steal Full publish rights until rotated
Provenance PEP 740 attestations (signed, verifiable) None by default
Setup One-time publisher registration on PyPI Generate token + store secret
Best for All CI/CD releases Legacy CI, emergency local upload

If a repo currently uses a token, migrating to OIDC is strictly an upgrade — see references/trusted-publishing.md.

The #1 gotcha: first publish needs a pending publisher

A Trusted Publisher is normally configured under the project's settings on PyPI — but on the first ever publish the project doesn't exist yet, so there's nothing to configure it under. The fix is a pending publisher, registered at the account level before the first upload.

Symptom (the exact failure this skill exists to kill):

Trusted publishing exchange failure:
* invalid-publisher: valid token, but no corresponding publisher
  (Publisher with matching claims was not found)

The OIDC token was valid; PyPI just has no publisher matching the claims. Fix:

PyPI → https://pypi.org/manage/account/publishing/ → Add a pending publisher

Field Value
PyPI Project Name the dist name from pyproject.toml [project].name
Owner GitHub org/user
Repository name repo name
Workflow name the filename, e.g. publish.yml (not the name:)
Environment name must equal the job's environment: (e.g. pypi)

All four claims must match the run's OIDC token exactly. After the first successful publish, the pending publisher auto-converts to a normal project publisher — no further action. Run diagnose-publish.sh on a failed run to read the exact claims it presented and compare them field-by-field.

This is the most common silent-failure mode: a package's publish.yml looks perfect and every release builds green, yet nothing ever reaches PyPI because the publisher was never registered. Check it first.

Recommended workflow (copy assets/publish.yml)

The shipped template is hardened to the patterns below — adapt the marked points and drop it in .github/workflows/. Non-negotiables it encodes:

  • on: push: tags: ['v*'] — release on a version tag, never on every push.
  • OIDC, no token: the publish job has permissions: id-token: write and pypa/gh-action-pypi-publish with attestations: true. No password:/token.
  • environment: pypi on the publish job → a human approves every release (defense-in-depth: even a compromised repo can't auto-ship).
  • Build/publish split: a build job (no elevated perms) produces + uploads the dist artifact; publish downloads it. Least privilege per job.
  • uv sync --locked + pip-audit: the release is built against the committed, hash-verified lockfile and blocked if a dep has a known CVE.
  • twine check / metadata validation before upload.
  • SHA-pinned actions with a trailing # vX comment (mutable tags get hijacked — see check-action-pins.py).
  • Verify-on-PyPI tail job — polls the JSON API so a silent publish failure (accepted-but-not-live, CDN lag) surfaces loudly instead of looking fine.

Supply-chain hardening — the publisher side

Stealing your publish credential lets an attacker ship malware to everyone who installs you — so the publish path is the surface the 2026 worm campaign (Mini Shai-Hulud) targets, minting PyPI/npm tokens from stale OIDC trust and orphaned workflows. The template above isn't just convention; each choice is a defense:

Control Defends against
OIDC, no stored token Credential theft/phishing — there is no long-lived secret to steal
PEP 740 attestations Tampered artifacts — provenance is signed and verifiable
environment: pypi + reviewers A compromised repo/CI auto-shipping — a human still gates the release
pip-audit gate A knowingly-vulnerable dependency reaching the release build
SHA-pinned actions (check-action-pins.py) Action-tag hijacks (tj-actions, 2025) repointing @vN to a malicious commit
permissions: {} + per-job least privilege A poisoned build step escalating beyond read
uv sync --locked Build-time dependency injection / silent re-resolution

Then audit the trust itself, not just the workflow:

  • Revoke stale Trusted Publishers / OIDC federation you no longer use — an orphaned publisher bound to a deletable workflow is the Mini Shai-Hulud entry point. Review PyPI → project → Publishing periodically.
  • If a token is in play, rotate it (project-scoped, short-lived) — better, migrate to OIDC and delete it. See trusted-publishing.md.
  • Vet build dependencies before a release, not after — a poisoned uv sync step runs before your OIDC token is even minted.

Division of labour: pypi-ops owns publisher hardening; supply-chain-defense owns the install side and ships integrity-audit.sh (hunts pull_request_target

  • OIDC misconfig and worm persistence) — run it on any repo that publishes, and gate dependency bumps through its cooldown + behavioural scan.

Cutting a release — preflight then tag

Before tagging, run the preflight so a release never fails on something mechanical (version skew, dirty lock, missing publisher config):

scripts/publish-preflight.sh .                 # human summary; exit 10 = not ready
scripts/publish-preflight.sh --build .          # also build + twine-check the dist
scripts/publish-preflight.sh --json . | jq '.data[] | select(.ok==false)'

It checks: pyproject version == __init__.__version__, the version is not already on PyPI (uploads are immutable — you cannot re-push 1.2.3), the lockfile self-version matches, a tag (if present) matches the version, and the publish workflow uses OIDC (flags a stored token). --build additionally verifies the package actually builds and passes twine check. Dynamic-versioned projects (hatch-vcs / setuptools-scm) are read from the HEAD tag. Green → bump, commit, tag, push the tag; CI builds, waits at the pypi environment gate, you approve.

When a publish fails — classify, don't guess

scripts/diagnose-publish.sh <run-id>           # reads gh run log, names the cause + fix
gh run view <run-id> --log-failed | scripts/diagnose-publish.sh -   # or pipe a log

The high-frequency failure classes and their fixes:

Symptom Cause Fix
invalid-publisher / claims not found No (pending) publisher on PyPI Register the pending publisher (above)
File already exists / 400 on upload Version already on PyPI (immutable) Bump the version; never reuse — see recovery
Job stuck "Waiting" environment: pypi needs approval Approve the deployment in the run's UI
environment … not found Publisher claim names an env the job lacks Make environment: and the publisher's Environment match
Built green, not on PyPI Silent accept / no verify step Add the verify-on-PyPI job; re-run
non-OIDC/token rejected Token wrong/expired, or OIDC misread as token Prefer OIDC; if token, rotate + re-store

Full catalogue with the underlying mechanics: references/recovery-playbook.md.

Local & manual publishing (uv / twine)

For a one-off or a non-CI environment. Prefer uv in 2026 (faster, native):

uv build                                   # sdist + wheel into dist/
uv publish --trusted-publishing automatic  # OIDC if in supported CI, else prompts
# token path (store in ~/.pypirc or env, never inline on the CLI history):
UV_PUBLISH_TOKEN="pypi-…" uv publish

twine remains the canonical fallback and the metadata validator (the GitHub Action wraps it internally):

python -m twine check dist/*               # ALWAYS run before any upload
python -m twine upload dist/*              # token from ~/.pypirc; legacy path

Never hand-roll the HTTP upload. Details + ~/.pypirc shape: references/uv-publish.md.

Dry-run on TestPyPI first

For a brand-new package or a risky metadata change, publish to test.pypi.org first — it has its own separate accounts and its own pending-publisher registration. Point the action at repository-url: https://test.pypi.org/legacy/ and register the pending publisher on TestPyPI. See references/trusted-publishing.md.

Keeping the workflow from rotting

The pinned action SHAs and pypa/gh-action-pypi-publish major drift over time. The verifier flags it before a release does:

scripts/check-action-pins.py --offline .github/workflows/publish.yml   # structure: all pinned + commented
scripts/check-action-pins.py --live    .github/workflows/publish.yml   # resolve tags → flag SHA drift

--offline is the PR gate (every uses: is SHA-pinned with a # vX comment); --live runs scheduled (resolves each pin against GitHub and exits 10 on drift, 7 if GitHub is unreachable — advisory, never a flaky block).

Publishing many packages (a fleet)

When several repos publish the same way, don't copy publish.yml N times — each copy drifts its own SHA pins. Hoist the publish job into a reusable workflow (on: workflow_call) in one repo, and have each package's tiny caller pass its dist name. OIDC still works: the caller's workflow_ref is what PyPI matches, so register each package's pending publisher against the caller filename (e.g. release.yml), not the shared one. One place to refresh pins (check-action-pins.py on the reusable workflow); one approval gate definition; per-package publishers. See references/trusted-publishing.md for the claim that must match.

Reference files

File Load when
references/trusted-publishing.md Setting up OIDC, pending vs project publisher, OIDC claim semantics, environments, TestPyPI, token→OIDC migration
references/recovery-playbook.md A publish failed and you need the full failure-class catalogue + mechanics
references/uv-publish.md Local/manual publishing, uv build/uv publish, twine, ~/.pypirc, build backends
Files (claude-mods)
  • assets
    • publish.yml 4.4 KB
      Loading…
  • references
    • recovery-playbook.md 5.1 KB
      Loading…
    • trusted-publishing.md 4.7 KB
      Loading…
    • uv-publish.md 2.9 KB
      Loading…
  • scripts
    • check-action-pins.py 6.2 KB
      Loading…
    • diagnose-publish.sh 6.7 KB
      Loading…
    • publish-preflight.sh 10.4 KB
      Loading…
  • tests
    • run.sh 7.1 KB
      Loading…
  • SKILL.md 12.4 KB
    ---
    name: pypi-ops
    description: "Publish Python packages to PyPI via OIDC Trusted Publishing (PEP 740 attestations, gh-action-pypi-publish) instead of stored tokens. Use for: invalid-publisher errors, pending-publisher 404s, uv publish/twine, TestPyPI, environment approval gates, and rotating/auditing publish tokens."
    license: MIT
    compatibility: "Python 3.8+ packaging; GitHub Actions for the OIDC flow; uv or twine for local publish"
    allowed-tools: "Read Write Edit Bash Glob Grep WebFetch"
    metadata:
      author: claude-mods
      related-skills: "supply-chain-defense, github-ops, git-ops, ci-cd-ops, python-env"
    ---
    
    # PyPI Operations
    
    Publish Python packages to PyPI on the **2026 best-practice path: OIDC Trusted
    Publishing with signed PEP 740 attestations**, no long-lived token to leak. This
    skill owns the *publish* layer (the registry handshake, the first-publish
    gotchas, the recovery playbook). General GitHub Actions syntax is `ci-cd-ops`;
    the install-side worm defense is `supply-chain-defense`; `gh`/release-page
    mechanics are `github-ops`.
    
    ## Where this fits — the release pipeline
    
    A release spans several skills; pypi-ops owns the **registry** step. Chain them:
    
    1. **Vet dependencies** before cutting a release — `supply-chain-defense`
       (cooldown + behavioural scan). The build runs dependency code *before* it
       touches your publish credential, so a poisoned build dep can steal the token.
    2. **Preflight** — `scripts/publish-preflight.sh --build .` (this skill).
    3. **Bump → tag → push** — `git-ops` (its push-preflight scans for secrets /
       forbidden files before the tag goes up).
    4. **CI publishes** via OIDC — this skill's `assets/publish.yml`; you approve at
       the `pypi` environment gate.
    5. **Release page** (optional, GitHub) — `github-ops`, human-reviewed notes.
    
    ## The one decision: OIDC vs API token
    
    **Default to OIDC Trusted Publishing.** Reach for a token only when OIDC is
    impossible (publishing from a non-supported CI, or a one-off local push).
    
    | | **Trusted Publishing (OIDC)** ← default | **API token** |
    |---|---|---|
    | Secret stored | None — short-lived OIDC token minted per run | Long-lived `pypi-…` token in a secret |
    | Leak/phish blast radius | None to steal | Full publish rights until rotated |
    | Provenance | PEP 740 attestations (signed, verifiable) | None by default |
    | Setup | One-time publisher registration on PyPI | Generate token + store secret |
    | Best for | **All CI/CD releases** | Legacy CI, emergency local upload |
    
    If a repo currently uses a token, migrating to OIDC is strictly an upgrade — see
    [references/trusted-publishing.md](references/trusted-publishing.md).
    
    ## The #1 gotcha: first publish needs a *pending* publisher
    
    A Trusted Publisher is normally configured **under the project's settings** on
    PyPI — but on the **first ever publish the project doesn't exist yet**, so there's
    nothing to configure it under. The fix is a **pending publisher**, registered at
    the account level *before* the first upload.
    
    Symptom (the exact failure this skill exists to kill):
    
    ```
    Trusted publishing exchange failure:
    * invalid-publisher: valid token, but no corresponding publisher
      (Publisher with matching claims was not found)
    ```
    
    The OIDC token was valid; PyPI just has no publisher matching the claims. Fix:
    
    > **PyPI → https://pypi.org/manage/account/publishing/ → Add a pending publisher**
    >
    > | Field | Value |
    > |---|---|
    > | PyPI Project Name | the dist name from `pyproject.toml` `[project].name` |
    > | Owner | GitHub org/user |
    > | Repository name | repo name |
    > | Workflow name | the **filename**, e.g. `publish.yml` (not the `name:`) |
    > | Environment name | must equal the job's `environment:` (e.g. `pypi`) |
    
    All four claims must match the run's OIDC token exactly. After the first
    successful publish, the pending publisher auto-converts to a normal project
    publisher — no further action. Run `diagnose-publish.sh` on a failed run to read
    the exact claims it presented and compare them field-by-field.
    
    > This is the most common silent-failure mode: a package's `publish.yml` looks
    > perfect and every release builds green, yet nothing ever reaches PyPI because
    > the publisher was never registered. Check it **first**.
    
    ## Recommended workflow (copy [assets/publish.yml](assets/publish.yml))
    
    The shipped template is hardened to the patterns below — adapt the marked points
    and drop it in `.github/workflows/`. Non-negotiables it encodes:
    
    - **`on: push: tags: ['v*']`** — release on a version tag, never on every push.
    - **OIDC, no token:** the `publish` job has `permissions: id-token: write` and
      `pypa/gh-action-pypi-publish` with `attestations: true`. No `password:`/token.
    - **`environment: pypi`** on the publish job → a human approves every release
      (defense-in-depth: even a compromised repo can't auto-ship).
    - **Build/publish split:** a `build` job (no elevated perms) produces + uploads
      the `dist` artifact; `publish` downloads it. Least privilege per job.
    - **`uv sync --locked` + `pip-audit`:** the release is built against the
      committed, hash-verified lockfile and blocked if a dep has a known CVE.
    - **`twine check` / metadata validation** before upload.
    - **SHA-pinned actions** with a trailing `# vX` comment (mutable tags get
      hijacked — see `check-action-pins.py`).
    - **Verify-on-PyPI** tail job — polls the JSON API so a *silent* publish failure
      (accepted-but-not-live, CDN lag) surfaces loudly instead of looking fine.
    
    ## Supply-chain hardening — the publisher side
    
    Stealing your publish credential lets an attacker ship malware to everyone who
    installs you — so the publish path is the surface the 2026 worm campaign (Mini
    Shai-Hulud) targets, minting PyPI/npm tokens from **stale OIDC trust and orphaned
    workflows**. The template above isn't just convention; each choice is a defense:
    
    | Control | Defends against |
    |---|---|
    | OIDC, no stored token | Credential theft/phishing — there is no long-lived secret to steal |
    | PEP 740 attestations | Tampered artifacts — provenance is signed and verifiable |
    | `environment: pypi` + reviewers | A compromised repo/CI auto-shipping — a human still gates the release |
    | `pip-audit` gate | A knowingly-vulnerable dependency reaching the release build |
    | SHA-pinned actions (`check-action-pins.py`) | Action-tag hijacks (tj-actions, 2025) repointing `@vN` to a malicious commit |
    | `permissions: {}` + per-job least privilege | A poisoned build step escalating beyond read |
    | `uv sync --locked` | Build-time dependency injection / silent re-resolution |
    
    Then audit the **trust** itself, not just the workflow:
    
    - **Revoke stale Trusted Publishers / OIDC federation** you no longer use — an
      orphaned publisher bound to a deletable workflow is the Mini Shai-Hulud entry
      point. Review PyPI → project → *Publishing* periodically.
    - **If a token is in play, rotate it** (project-scoped, short-lived) — better,
      migrate to OIDC and delete it. See [trusted-publishing.md](references/trusted-publishing.md).
    - **Vet build dependencies before a release**, not after — a poisoned `uv sync`
      step runs before your OIDC token is even minted.
    
    Division of labour: **pypi-ops owns publisher hardening**; `supply-chain-defense`
    owns the install side and ships `integrity-audit.sh` (hunts `pull_request_target`
    + OIDC misconfig and worm persistence) — run it on any repo that publishes, and
    gate dependency bumps through its cooldown + behavioural scan.
    
    ## Cutting a release — preflight then tag
    
    Before tagging, run the preflight so a release never fails on something
    mechanical (version skew, dirty lock, missing publisher config):
    
    ```bash
    scripts/publish-preflight.sh .                 # human summary; exit 10 = not ready
    scripts/publish-preflight.sh --build .          # also build + twine-check the dist
    scripts/publish-preflight.sh --json . | jq '.data[] | select(.ok==false)'
    ```
    
    It checks: `pyproject` version == `__init__.__version__`, the version is **not
    already on PyPI** (uploads are immutable — you cannot re-push `1.2.3`), the
    lockfile self-version matches, a tag (if present) matches the version, and the
    publish workflow uses OIDC (flags a stored token). `--build` additionally
    verifies the package actually builds and passes `twine check`. Dynamic-versioned
    projects (hatch-vcs / setuptools-scm) are read from the HEAD tag. Green → bump,
    commit, tag, push the tag; CI builds, waits at the `pypi` environment gate, you
    approve.
    
    ## When a publish fails — classify, don't guess
    
    ```bash
    scripts/diagnose-publish.sh <run-id>           # reads gh run log, names the cause + fix
    gh run view <run-id> --log-failed | scripts/diagnose-publish.sh -   # or pipe a log
    ```
    
    The high-frequency failure classes and their fixes:
    
    | Symptom | Cause | Fix |
    |---|---|---|
    | `invalid-publisher` / claims not found | No (pending) publisher on PyPI | Register the pending publisher (above) |
    | `File already exists` / 400 on upload | Version already on PyPI (immutable) | Bump the version; never reuse — see [recovery](references/recovery-playbook.md) |
    | Job stuck "Waiting" | `environment: pypi` needs approval | Approve the deployment in the run's UI |
    | `environment … not found` | Publisher claim names an env the job lacks | Make `environment:` and the publisher's Environment match |
    | Built green, not on PyPI | Silent accept / no verify step | Add the verify-on-PyPI job; re-run |
    | `non-OIDC`/token rejected | Token wrong/expired, or OIDC misread as token | Prefer OIDC; if token, rotate + re-store |
    
    Full catalogue with the underlying mechanics: [references/recovery-playbook.md](references/recovery-playbook.md).
    
    ## Local & manual publishing (uv / twine)
    
    For a one-off or a non-CI environment. **Prefer `uv` in 2026** (faster, native):
    
    ```bash
    uv build                                   # sdist + wheel into dist/
    uv publish --trusted-publishing automatic  # OIDC if in supported CI, else prompts
    # token path (store in ~/.pypirc or env, never inline on the CLI history):
    UV_PUBLISH_TOKEN="pypi-…" uv publish
    ```
    
    `twine` remains the canonical fallback and the metadata validator (the GitHub
    Action wraps it internally):
    
    ```bash
    python -m twine check dist/*               # ALWAYS run before any upload
    python -m twine upload dist/*              # token from ~/.pypirc; legacy path
    ```
    
    Never hand-roll the HTTP upload. Details + `~/.pypirc` shape:
    [references/uv-publish.md](references/uv-publish.md).
    
    ## Dry-run on TestPyPI first
    
    For a brand-new package or a risky metadata change, publish to **test.pypi.org**
    first — it has its own separate accounts *and its own pending-publisher
    registration*. Point the action at `repository-url: https://test.pypi.org/legacy/`
    and register the pending publisher on TestPyPI. See
    [references/trusted-publishing.md](references/trusted-publishing.md#testpypi).
    
    ## Keeping the workflow from rotting
    
    The pinned action SHAs and `pypa/gh-action-pypi-publish` major drift over time.
    The verifier flags it before a release does:
    
    ```bash
    scripts/check-action-pins.py --offline .github/workflows/publish.yml   # structure: all pinned + commented
    scripts/check-action-pins.py --live    .github/workflows/publish.yml   # resolve tags → flag SHA drift
    ```
    
    `--offline` is the PR gate (every `uses:` is SHA-pinned with a `# vX` comment);
    `--live` runs scheduled (resolves each pin against GitHub and exits 10 on drift,
    7 if GitHub is unreachable — advisory, never a flaky block).
    
    ## Publishing many packages (a fleet)
    
    When several repos publish the same way, don't copy `publish.yml` N times — each
    copy drifts its own SHA pins. Hoist the publish job into a **reusable workflow**
    (`on: workflow_call`) in one repo, and have each package's tiny caller pass its
    dist name. OIDC still works: the *caller's* `workflow_ref` is what PyPI matches,
    so **register each package's pending publisher against the caller** filename
    (e.g. `release.yml`), not the shared one. One place to refresh pins
    (`check-action-pins.py` on the reusable workflow); one approval gate definition;
    per-package publishers. See [references/trusted-publishing.md](references/trusted-publishing.md)
    for the claim that must match.
    
    ## Reference files
    
    | File | Load when |
    |---|---|
    | [references/trusted-publishing.md](references/trusted-publishing.md) | Setting up OIDC, pending vs project publisher, OIDC claim semantics, environments, TestPyPI, token→OIDC migration |
    | [references/recovery-playbook.md](references/recovery-playbook.md) | A publish failed and you need the full failure-class catalogue + mechanics |
    | [references/uv-publish.md](references/uv-publish.md) | Local/manual publishing, `uv build`/`uv publish`, `twine`, `~/.pypirc`, build backends |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.