Metadata-Version: 2.5
Name: bktools
Version: 0.3.0.post16+gcd8b49f95
Summary: Buildkite-invoked helper tools
Requires-Python: >=3.12
Requires-Dist: click>=8.3.3
Requires-Dist: manifest-builder>=0.4.1.dev18
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# Buildkite Tools

Small Python tools intended to be invoked from Buildkite pipelines.

## Development

This project uses [uv](https://docs.astral.sh/uv/) for development. To set up the
environment, run `uv sync`. Tests and checks can be run with:

```bash
uv run ruff check
uv run ruff format --check
uv run ty check
uv run pytest
```

## Tools

- `pipelinegen`: generate Buildkite pipeline YAML from `.buildkite/pipelinegen.toml`,
  write it to `pipeline.yaml`, upload that file as a Buildkite artifact, and
  upload it with `buildkite-agent pipeline upload`. Use `--dump` to write the
  generated YAML to stdout instead. To preview container publishing locally, run
  `BUILDKITE_BRANCH=main pipelinegen --dump --assume-image-exists=false`.
  `--assume-image-exists=true|false` bypasses the registry check: `false`
  generates the build steps, while `true` takes the existing-image path.
  - `variant = "rust"`: Rust build/test.
  - `variant = "uv"`: uv/ruff/pytest/build/ty checks plus a main-branch Python
    package publish step.
  - `variant = "manifest-builder"`: use `repo` as the manifest output
    repository. On pull request builds, generate a diff comment through the
    `diffcomment` entrypoint. On other builds, clone the output
    repository, run `manifest_builder.generate()` with the current checkout as
    input and the cloned repository as output, create a manifest commit, and push
    it through the `manifest-builder-on-checkout` entrypoint.

    ```toml
    variant = "manifest-builder"
    repo = "https://github.com/example/manifests.git"
    ```
  - `variant = "relcoord"`: request manifest generation through relcoord in
    system mode. Pull request builds call `/v1/diffcomment`; main-branch builds
    call `/v1/change`. Other branches add no steps. The relcoord token's role
    must allow system requests.

    ```toml
    variant = "relcoord"
    relcoord-endpoint = "relcoord.example.com"
    ```
  - `output = "container"`: add a main-branch Docker publish step using
    OIDC registry login and `docker buildx build` with zstd-compressed image
    output. Before adding build steps, check whether the exact image tag already
    exists in the registry. If it does, skip the build and call the configured
    relcoord endpoint directly with the current config; without an endpoint,
    no additional steps are needed.
  - `container-architecture = "arm64"`: build and publish only the selected
    container architecture (`arm64` or `amd64`) and push the tagged image directly
    from the build step. When omitted, build both and publish a combined manifest.
  - `relcoord-endpoint = "relcoord.example.com"`: after a container image is
    built and pushed, call
    `uvx --from bktools --index https://repo.noa.re notify-relcoord relcoord.example.com --repo ... --tag ...`.
  - `variant = "rust-container"` is deprecated. Use `variant = "rust"` with
    `output = "container"` instead.
- `bktools-image-version-hash`: hash a Docker build context and optionally emit a
  Docker tag. The base version comes from `Cargo.toml` when present, otherwise
  from the nearest reachable `vX.Y.Z` git tag.
- `diffcomment`: generate a manifest diff comment for a pull request. It reads
  Buildkite environment variables by default; pass `--ci-system=github` to read
  GitHub Actions pull request context instead. Pass `--pr-comment-token` with a
  GitHub token to post the comment via the GitHub REST API, and
  `--target-clone-token` to authenticate the `--target-repo` clone where ambient
  credentials are unavailable.
- `get-installation-token`: obtain a GitHub App installation token from an idcat
  endpoint. It requests a Buildkite OIDC token whose audience is `--endpoint`
  without the scheme or trailing slash, exchanges it at
  `--endpoint/installation-token/OWNER/REPO`, and prints the resulting token to
  stdout.
- `notify-relcoord`: notify a relcoord endpoint about a published container
  image. The tool takes the endpoint as a positional argument, requests a
  Buildkite OIDC token for that audience, and posts the current
  `BUILDKITE_COMMIT`, `BUILDKITE_REPO`, tag, and OCI image repository such as
  `repo.noa.re/idmouse` to `/v1/change` as `commit`, `config_repo`, `tag`, and
  `image_repo`.
- `notify-relcoord --system`: send the current Buildkite repository and commit
  to relcoord with `system = true`. Add `--diffcomment` to comment on the current
  pull request; otherwise relcoord generates and pushes manifests.
