Skip to content

docs: refresh PyPI install guidance #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saagpatel merged 1 commit into from
May 18, 2026
Merged

docs: refresh PyPI install guidance #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
## [Unreleased]

### Changed
- Updated public install documentation now that `github-repo-auditor` is live on
PyPI.
- Added a manual PyPI Trusted Publishing workflow that builds a release tag and
publishes from a protected `pypi` environment after PyPI is configured.
- Made PyPI publishing explicitly opt-in while keeping GitHub Releases as the supported public distribution path.
Expand Down
19 changes: 13 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,16 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score

### Installation

The package is published as GitHub release artifacts today. PyPI/package-index publishing is not active yet, so registry commands like `pip install github-repo-auditor` are not the recommended public path. See [docs/distribution.md](docs/distribution.md) for the current distribution policy.
The package is published on PyPI and through GitHub Releases. For normal CLI use,
install it as an isolated tool:

```bash
# uv (recommended)
uv tool install github-repo-auditor

# pipx
pipx install github-repo-auditor
```

Fastest no-clone path:

Expand All @@ -148,13 +157,10 @@ chmod +x audit.pyz
./audit.pyz --help
```

Install from the public GitHub source:
Install from the public GitHub source when you want the latest unreleased code:

```bash
# uv (recommended)
uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'

# pipx
pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'

# local editable clone
Expand All @@ -165,11 +171,12 @@ pip install -e ".[config]"

The self-contained `.pyz` binary is also available from the
[GitHub Releases](https://github.com/saagpatel/GithubRepoAuditor/releases) page.
See [docs/distribution.md](docs/distribution.md) for the release and publishing policy.

For the local web UI, install the `[serve]` extra from source:

```bash
uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
pip install "github-repo-auditor[serve]"

@chatgpt-codex-connector chatgpt-codex-connector Bot May 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Document serve extras for isolated installs

When a user follows the recommended uv tool install or pipx install path above and later wants the web UI, this pip install command installs the [serve] extra into whatever Python environment pip targets, not into the already-created isolated tool environment. The audit executable from uv/pipx will still hit _run_serve_mode's missing-extra path unless the extra is installed into that tool environment, so the README should give a tool-aware reinstall/inject command for github-repo-auditor[serve] rather than plain pip install.

Useful? React with 👍 / 👎.

# or from a clone: pip install -e ".[serve]"
```

Expand Down
44 changes: 24 additions & 20 deletions docs/distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@
# Distribution

GitHub Repo Auditor is public and currently distributed through GitHub Releases.
GitHub Repo Auditor is public and distributed through PyPI and GitHub Releases.

## Current Public Path

Use PyPI for the normal CLI install:

```bash
uv tool install github-repo-auditor
pipx install github-repo-auditor
```

Use the latest release binary when you want the fastest no-clone install:

```bash
Expand All @@ -12,7 +19,7 @@ chmod +x audit.pyz
./audit.pyz --help
```

Use the public GitHub source when you want an isolated tool install:
Use the public GitHub source when you want the latest unreleased code:

```bash
uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
Expand All @@ -21,33 +28,30 @@ pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'

## PyPI Status

PyPI publishing is not active yet. The package name `github-repo-auditor` was
available when checked during the public-readiness pass on 2026-05-18, but that
can change and should be rechecked immediately before first publication.
PyPI publishing is active for `github-repo-auditor`.

The repository is prepared for a future PyPI release:
The repository uses GitHub Actions Trusted Publishing:

- package metadata lives in `pyproject.toml`
- `make build` creates the wheel and source distribution
- `make dist-check` runs `twine check`
- `scripts/release.sh` builds and checks artifacts by default
- `scripts/release.sh --publish-pypi` is the only script path that uploads to PyPI
- `scripts/release.sh --publish-pypi` remains an explicit local fallback only
- `.github/workflows/pypi.yml` is a manual Trusted Publishing workflow for a
release tag, using the `pypi` environment and short-lived OIDC credentials

## Activation Checklist
## Release Checklist

Before the first PyPI release:
For a normal public release:

1. Recheck that the `github-repo-auditor` PyPI name is still available.
2. Configure PyPI Trusted Publishing for owner `saagpatel`, repository
`GithubRepoAuditor`, workflow `pypi.yml`, and environment `pypi`.
3. Protect the GitHub `pypi` environment so publishing requires intentional
approval.
4. Run the standard and distribution gates from [release-gates.md](release-gates.md).
5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the release tag,
for example `v0.1.1`.
6. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`.
1. Run the standard and distribution gates from [release-gates.md](release-gates.md).
2. Create a PEP 440-compatible `v*` tag from the verified `main` commit.
3. Wait for the GitHub Release workflow to publish the wheel, source distribution,
and `audit.pyz` assets.
4. Smoke-test the GitHub Release `audit.pyz`.
5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the same release
tag, for example `v0.1.3`.
6. Approve the protected `pypi` environment.
7. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`.

Until that checklist is complete, GitHub Releases remain the supported public
distribution channel.
GitHub Releases and PyPI should always publish the same tag.
6 changes: 4 additions & 2 deletions tests/test_distribution_policy.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,10 @@ def test_distribution_docs_name_supported_public_channel() -> None:
release_gates = (ROOT / "docs" / "release-gates.md").read_text()
workflows_readme = (ROOT / ".github" / "workflows" / "README.md").read_text()

assert "GitHub Releases remain the supported public" in distribution_doc
assert "PyPI publishing is not active yet" in distribution_doc
assert "distributed through PyPI and GitHub Releases" in distribution_doc
assert "PyPI publishing is active" in distribution_doc
assert "uv tool install github-repo-auditor" in readme
assert "pipx install github-repo-auditor" in readme
assert "docs/distribution.md" in readme
assert "scripts/release.sh --publish-pypi" in release_gates
assert "pypi.yml" in workflows_readme
Expand Down