Skip to content

GITHUB_PYPI_SETUP.md

Latest commit

 

History

History
138 lines (100 loc) · 4.31 KB

GITHUB_PYPI_SETUP.md

File metadata and controls

138 lines (100 loc) · 4.31 KB

GitHub + PyPI Setup Guide

This checklist takes a local pgpkg repository to a production-ready GitHub repository with automated PyPI publishing.

1) Create and push the GitHub repository

  1. Create an empty GitHub repo (for example, pgpkg).
  2. Add the remote and push:
git remote add origin git@github.com:<OWNER>/pgpkg.git
git push -u origin <BRANCH>
  1. Push all long-lived branches you want preserved.

2) Repository settings (recommended hygiene)

  1. Enable branch protection on the default branch:
    • Require pull request before merging
    • Require status checks to pass
    • Require branches to be up to date before merging
  2. Require these checks from CI:
    • quality
    • unit (3.11)
    • unit (3.12)
    • unit (3.13)
    • integration (postgres:14-alpine)
    • integration (postgres:15-alpine)
    • integration (postgres:16-alpine)
    • integration (postgres:17-alpine)
    • build-docs
  3. Enable "Automatically delete head branches" after merge.
  4. Enable Dependabot alerts and security updates.
  5. In Settings -> Pages, set Source to GitHub Actions so .github/workflows/docs-pages.yml can publish the MkDocs site.

3) PyPI account and project prerequisites

You need an account on:

Required access

  • You must be an Owner or Maintainer for the project on PyPI.
  • You must have admin rights on the GitHub repository to configure environments and workflows.

4) Preferred publishing model: Trusted Publishing (OIDC)

This repository already includes .github/workflows/publish-pypi.yml, which is configured for trusted publishing.

4a) Configure GitHub environments

Create these environments in GitHub:

  • pypi

Optional hardening:

  • Add required reviewers for pypi environment
  • Restrict deployment branches/tags

4b) Configure trusted publisher on PyPI

In PyPI project settings, add a trusted publisher with:

  • Owner: <OWNER>
  • Repository: pgpkg
  • Workflow filename: publish-pypi.yml
  • Environment: pypi

5) Credentials you actually need

With trusted publishing configured correctly:

  • No PyPI API token is needed in GitHub secrets.
  • No username/password is needed in CI.
  • The only required "credential" in CI is GitHub's OIDC identity (id-token: write, already set in workflow).

You still need:

  • GitHub account with repo admin rights
  • PyPI account with project owner/maintainer rights

6) Optional fallback model: API token publishing

Only use this if trusted publishing cannot be enabled.

  1. Create a project-scoped API token in PyPI.
  2. Add these repository secrets:
    • PYPI_API_TOKEN
  3. Update publish workflow to pass password: ${{ secrets.<TOKEN_NAME> }} to pypa/gh-action-pypi-publish.

7) First release flow

  1. Run local gate:
uv run pre-commit run --all-files
uv run ty check src tests
uv run pytest -q
uv build --out-dir dist
uv run python -m twine check dist/*
uv run mkdocs build --strict
  1. Create GitHub Release tag v0.1.0 to trigger PyPI publish.

Optional manual path:

  • GitHub Actions -> Publish -> Run workflow -> expected_version=0.1.0
  1. Verify install from PyPI:
uv venv /tmp/pgpkg-smoke
uv pip install --python /tmp/pgpkg-smoke/bin/python pgpkg
/tmp/pgpkg-smoke/bin/pgpkg --help

The Publish workflow's build job also smoke-tests a generated wrapper wheel, so a successful publish already validates both the base CLI wheel and the wrapper packaging path before upload.

TestPyPI is intentionally not wired up in this repository right now. If access is restored later, add a separate environment and publish job rather than reusing the PyPI lane implicitly.

8) Post-setup metadata cleanup

Add canonical URLs in pyproject.toml:

[project.urls]
Homepage = "https://github.com/<OWNER>/pgpkg"
Repository = "https://github.com/<OWNER>/pgpkg"
Documentation = "https://<OWNER>.github.io/pgpkg/"
Issues = "https://github.com/<OWNER>/pgpkg/issues"

9) Quick troubleshooting

  • "invalid-publisher" or "publisher not trusted": trusted publisher fields do not exactly match repo/workflow/environment. For this repo, confirm bitner/pgpkg, workflow publish-pypi.yml, and environment pypi exactly.
  • Publish job not starting: verify environment name in workflow matches configured environment.
  • Artifact missing in publish job: ensure build job used uv build --out-dir dist and uploaded dist/*.