Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 4 additions & 4 deletions .github/workflows/_checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
# Pin the TOOL, not just the action that installs it: without
# this, every run fetches whatever `just` was released last.
just-version: "1.58.0"
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
# Static checks only need a single modern interpreter; the test
# matrix is what proves the >=3.11 floor. pythonVersion in pyright
Expand Down Expand Up @@ -85,7 +85,7 @@ jobs:
# Pin the TOOL, not just the action that installs it: without
# this, every run fetches whatever `just` was released last.
just-version: "1.58.0"
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
# Selects the interpreter for this matrix leg via UV_PYTHON. This
# overrides the 3.14 pin in .python-version, which is only the local
Expand Down Expand Up @@ -114,7 +114,7 @@ jobs:
# Pin the TOOL, not just the action that installs it: without
# this, every run fetches whatever `just` was released last.
just-version: "1.58.0"
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
python-version: "3.13"
- name: Sync dev dependencies
Expand All @@ -124,7 +124,7 @@ jobs:
# proves the wheel ships py.typed and the sdist ships nothing internal.
run: just build
- name: Upload distribution artifact
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: dist
path: dist/
4 changes: 2 additions & 2 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
- uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
languages: python
# Python is interpreted; there is nothing to build for analysis.
build-mode: none
- uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
- uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
category: "/language:python"
66 changes: 55 additions & 11 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,14 @@ jobs:
# Pin the TOOL, not just the action that installs it: without
# this, every run fetches whatever `just` was released last.
just-version: "1.58.0"
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
python-version: "3.13"
# The cache is shared with every pull-request run, so restoring it
# here would let a poisoned entry reach the artifacts that get signed
# and published to PyPI (zizmor's cache-poisoning audit). A cold
# sync costs seconds, and only on a release.
enable-cache: false
- name: Sync dev dependencies
run: uv sync --locked
# Rebuilt here rather than downloaded from `checks`: an artifact round
Expand Down Expand Up @@ -114,8 +119,8 @@ jobs:
run: |
# --verify-tag refuses to invent a tag that was never pushed.
# A tag with a letter after the patch number (v0.1.0rc1, v0.1.0a1) is
# a pre-release: it stays out of "latest" and out of the README's
# install snippet.
# a pre-release: it stays out of "latest" here, and pip skips it on
# PyPI unless asked for with --pre or an exact pin.
prerelease=""
case "${TAG#v}" in *[a-z]*) prerelease="--prerelease" ;; esac
gh release create "$TAG" dist/* \
Expand All @@ -124,12 +129,51 @@ jobs:
--notes-file "$RUNNER_TEMP/notes.md" \
--verify-tag \
$prerelease
# Hand the exact bytes that were just signed and released to the publish
# job, so PyPI and the GitHub Release can never disagree. Only the wheel
# and sdist: the uploader rejects anything that is not a distribution,
# which includes the .sigstore.json bundles sitting beside them.
- name: Hand the released artifacts to the PyPI job
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: pypi-dist
path: |
dist/*.whl
dist/*.tar.gz
if-no-files-found: error

# Publishing to PyPI is deliberately off: consumers install the wheel from the
# GitHub Release above. To re-enable it, add a `publish` job here with
# `needs: [release]`, `environment: pypi`, `permissions: { id-token: write }`,
# and `pypa/gh-action-pypi-publish` — nothing above this line changes. Its
# id-token is its own: trusted publishing binds the token to that job, so it
# does not reuse the one the signing step above mints. It
# requires a one-time PyPI trusted-publisher pointing at this workflow and that
# environment; publishing fails until that exists.
publish:
name: Publish to PyPI
# After the GitHub Release, not before: a PyPI filename can never be
# uploaded twice, even after deletion, so this is the one step that cannot
# be retried by rebuilding. Running it last means a failure here (PyPI
# down, publisher misconfigured) is fixed with "Re-run failed jobs" on the
# same artifact, and never costs a version number.
needs: [release]
if: github.ref_type == 'tag'
runs-on: ubuntu-latest
# Trusted publishing binds the PyPI publisher to this workflow AND this
# environment, which is restricted to v* tags.
# It has no reviewers of its own: approving `release` is the deliberate
# act, and this job only runs once that job has succeeded.
environment:
name: pypi
url: https://pypi.org/project/bronto-sdk/
permissions:
# The OIDC token PyPI exchanges for a short-lived upload credential, and
# that the action uses to sign PEP 740 attestations. It is minted for this
# job alone; it is not the one the signing step above used. No `contents`
# permission and no checkout: the job holding the PyPI identity runs no
# project code, only the two pinned actions below.
id-token: write
steps:
- name: Fetch the artifacts the release job signed
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: pypi-dist
path: dist/
# Defaults do the right thing and are left implicit: trusted publishing
# (no token, no secret), PEP 740 attestations, and a metadata check
# before anything is uploaded.
- name: Upload to PyPI
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
6 changes: 3 additions & 3 deletions .github/workflows/scorecard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,17 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
- uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
with:
results_file: results.sarif
results_format: sarif
# Requires a public repository; it is forced off on a private one.
publish_results: true
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: SARIF file
path: results.sarif
retention-days: 5
- uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
- uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: results.sarif
2 changes: 1 addition & 1 deletion .github/workflows/zizmor.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.4
- uses: zizmorcore/zizmor-action@85b2b9fb8e3325e7a23d7d0a9d7ba5ae0f999e3e # v0.7.1
with:
# No GitHub Advanced Security on this repo; annotate inline instead.
advanced-security: false
Expand Down
28 changes: 27 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,37 @@ Breaking changes are listed first with a ⚠️ prefix.

## [Unreleased]

## [0.2.1] - 2026-11-11

### Added

- **Published on [PyPI](https://pypi.org/project/bronto-sdk/)** — install with
`pip install bronto-sdk` (or `bronto-sdk[mcp]`) instead of a GitHub Release
URL or a `git+https` requirement. Uploads use Trusted Publishing from the
release workflow (no API token exists) and carry PEP 740 provenance
attestations; PyPI receives exactly the files that are Sigstore-signed and
attached to the GitHub Release, which continues as before.
[SECURITY.md](https://github.com/bronto-community/bronto-sdk-python/blob/main/SECURITY.md#verifying-a-release)
covers verifying both.

### Security

- Refreshed `uv.lock` to PyJWT 2.15.1 and urllib3 2.8.0. Both reach the lock
only through the `mcp`/`langchain` extras and dev tooling; the SDK never
imports them and its published dependency ranges are unchanged, so installed
users resolve their own versions and are not affected.
- Refreshed `uv.lock` to certifi 2026.10.23, which drops the emSign root CAs
whose intermediate keys were compromised (GHSA-6q48-6c7w-9gw2). certifi
reaches the lock only transitively through `httpx`; the SDK's published
dependency ranges are unchanged, so installed users resolve their own
certifi and should upgrade it in their own environments.

### Changed

- Refreshed `uv.lock` to pydantic 2.14.1, langchain-core 1.7.3, and newer dev
tooling (ruff 0.17.3, pytest 9.2.0, pytest-mock 3.17.0, pytest-asyncio
1.4.1.post1), and bumped the pinned CI actions. Published dependency ranges
are unchanged.

## [0.2.0] - 2026-09-29

Expand Down Expand Up @@ -108,7 +133,8 @@ Automatic retries and backoff, pagination iterators, an MCP session opener,
LangChain tool decorators, OpenTelemetry hooks, an ingestion client (URL helper
only), and REST coverage beyond the five operations above.

[Unreleased]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.2.0...HEAD
[Unreleased]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.2.1...HEAD
[0.2.1]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.2.0...v0.2.1
[0.2.0]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.1.2...v0.2.0
[0.1.2]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.1.0...v0.1.2
[0.1.0]: https://github.com/bronto-community/bronto-sdk-python/releases/tag/v0.1.0
49 changes: 43 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,16 @@ and `pyproject.toml` in one step.

## Releasing (maintainers)

Releases are **GitHub Releases**, not PyPI. A `vX.Y.Z` tag push runs
`release.yml`, which builds the sdist and wheel and attaches both to a release
consumers install from. Publishing to PyPI is deliberately off; the note at the
foot of `.github/workflows/release.yml` records how to turn it on.
A `vX.Y.Z` tag push runs `release.yml`, which builds the sdist and wheel,
attaches both to a **GitHub Release**, then publishes the very same files to
**[PyPI](https://pypi.org/project/bronto-sdk/)**. PyPI is what consumers
install from (`pip install bronto-sdk`).

PyPI uploads use [Trusted Publishing](https://docs.pypi.org/trusted-publishers/):
the `publish` job exchanges a short-lived GitHub OIDC token for an upload
credential, so there is no PyPI API token to store, rotate or leak. Do not add
one, and do not upload by hand with `twine` — a hand upload has no attestation
and is indistinguishable from a compromised one.

To cut a release:

Expand All @@ -95,7 +101,20 @@ To cut a release:
`release` environment; approve it from the run's page in the Actions tab.
Either maintainer on the reviewer list can approve, including the person who
pushed the tag — the gate is there to make a release a deliberate, recorded
act, not to force a second pair of hands.
act, not to force a second pair of hands. The `publish` job runs on its own
once the GitHub Release exists; it needs no second approval.
6. Check [pypi.org/project/bronto-sdk](https://pypi.org/project/bronto-sdk/)
shows the version, with "Provenance" on each file.

If `publish` fails after the GitHub Release succeeded (PyPI outage,
misconfigured publisher), fix the cause and use **Re-run failed jobs** on the
same run. It re-uploads the artifacts the release job already signed; nothing
is rebuilt and no version is spent.

**A PyPI version is as permanent as its tag.** PyPI never accepts the same file
name twice, even after the release is deleted. A bad release is yanked on PyPI
(which hides it from new resolutions without breaking existing pins) and
superseded by the next patch version — never deleted and re-uploaded.

Signing is automatic and needs nothing from you: the workflow signs both
artifacts with Sigstore using its own short-lived OIDC identity, verifies the
Expand All @@ -109,7 +128,25 @@ pull request is.

**Rehearse with `workflow_dispatch`, not with a tag.** Running `release.yml`
from `main` exercises the version gate, the full test matrix and the build; the
release job is skipped because there is no tag.
release and publish jobs are skipped because there is no tag.

### One-time PyPI setup

Already done for this repository; recorded so it can be checked or rebuilt.
Trusted Publishing only works when both sides name each other exactly:

- **PyPI**: the `bronto-sdk` project (owned by the Bronto PyPI organization) has
a GitHub trusted publisher with owner `bronto-community`, repository
`bronto-sdk-python`, workflow `release.yml`, environment `pypi`. Before the
first upload this is a *pending* publisher, added from the organization's
Publishing page so the project is created under the organization.
- **GitHub**: a `pypi` environment (Settings → Environments) whose deployment
policy allows `v*` tags only, and no reviewers — approving `release` is the
gate. Restricting it to tags means a workflow run from a branch cannot obtain
a token PyPI will accept, even if the workflow file is edited on that branch.

Renaming the workflow file or the environment breaks publishing until the PyPI
publisher is updated to match.

Do not push a throwaway `vX.Y.Zrc1` tag to rehearse. A repository ruleset makes
every `v*` tag immutable — it cannot be moved or deleted once pushed, by anyone,
Expand Down
35 changes: 16 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,19 @@
# bronto-sdk

[![CI](https://github.com/bronto-community/bronto-sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/bronto-community/bronto-sdk-python/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/bronto-community/bronto-sdk-python)](https://github.com/bronto-community/bronto-sdk-python/releases)
[![PyPI](https://img.shields.io/pypi/v/bronto-sdk)](https://pypi.org/project/bronto-sdk/)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/bronto-community/bronto-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/bronto-community/bronto-sdk-python)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://github.com/bronto-community/bronto-sdk-python)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/bronto-sdk)](https://pypi.org/project/bronto-sdk/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bronto-community/bronto-sdk-python/blob/main/LICENSE)

Python SDK for the [Bronto](https://bronto.io) observability platform.

## Installation

The SDK is not on PyPI. Install the wheel attached to a
[GitHub Release](https://github.com/bronto-community/bronto-sdk-python/releases),
pinned to a version:

```bash
pip install https://github.com/bronto-community/bronto-sdk-python/releases/download/v0.2.0/bronto_sdk-0.2.0-py3-none-any.whl
```

Or build from the tag, which works in a `requirements.txt` because the
requirement is named:

```bash
pip install "bronto-sdk @ git+https://github.com/bronto-community/bronto-sdk-python@v0.2.0"
pip install bronto-sdk
# or
uv add bronto-sdk
```

Requires Python 3.11 or newer. The only runtime dependencies are `httpx`,
Expand All @@ -33,9 +24,15 @@ reserved so adding it later is not a breaking rename. The `mcp` extra installs
what `bronto_sdk.mcp` needs:

```bash
pip install "bronto-sdk[mcp] @ git+https://github.com/bronto-community/bronto-sdk-python@v0.2.0"
pip install "bronto-sdk[mcp]"
```

PyPI uploads carry provenance attestations, and every release is also
attached, with Sigstore signatures, to a
[GitHub Release](https://github.com/bronto-community/bronto-sdk-python/releases).
[SECURITY.md](https://github.com/bronto-community/bronto-sdk-python/blob/main/SECURITY.md#verifying-a-release)
covers verifying either.

## Quickstart

### Sync
Expand Down Expand Up @@ -337,10 +334,10 @@ just prepare # format, lint, typecheck, spec digest gate, tests
```

`just prepare` must be green before every commit. Run `just --list` to see
every recipe, and see [CONTRIBUTING.md](CONTRIBUTING.md) for the full setup.
every recipe, and see [CONTRIBUTING.md](https://github.com/bronto-community/bronto-sdk-python/blob/main/CONTRIBUTING.md) for the full setup.

Runnable versions of everything above live in [`examples/`](examples/).
Runnable versions of everything above live in [`examples/`](https://github.com/bronto-community/bronto-sdk-python/tree/main/examples).

## License

MIT — see [LICENSE](LICENSE).
MIT — see [LICENSE](https://github.com/bronto-community/bronto-sdk-python/blob/main/LICENSE).
Loading
Loading