Pulp Tool

A Python client for Pulp API operations including RPM and file management.

Overview: Setup · Usage and API · Development · License

Setup

Konflux / Red Hat Pulp access (primary)

In Konflux, Pulp access is provisioned by the pulp-access-controller operator—not by hand-editing cli.toml or creating terms-based registry credentials yourself.

1. Create a PulpAccessRequest in your namespace (see the operator README and Konflux: Getting access to Pulp storage).
2. The controller creates a pulp-access secret with cli.toml, authentication material, and domain name (konflux-<namespace>). It uses Red Hat's terms-based registry for credentials—you do not create those credentials yourself; the controller generates and manages them.

Tekton tasks mount that secret (for example /pulp-access/cli.toml) and run pulp-tool --config …. See CLAUDE.md for downstream flag and path contracts.

Local install and manual config

Clone and install:

git clone https://github.com/konflux-ci/pulp-tool.git
cd pulp-tool
pip install -e .

For development (dev dependencies and pre-commit):

pip install -e ".[dev]"

Create ~/.config/pulp/cli.toml for local use when you are not consuming a controller-generated pulp-access secret. Use the [cli] keys pulp-tool reads: base_url, api_root, domain, OAuth (client_id, client_secret) or Basic Auth (username, password), optional client cert (cert, key), and optional correlation_id for X-Correlation-ID (or set PULP_TOOL_CORRELATION_ID). See docs/cli-reference.md for access provisioning and command flags.

When --build-id and --namespace are set and no correlation id is configured, the client sends X-Correlation-ID: {namespace}/{build_id} (or the build id alone if namespace is omitted), similar to pulp-cli.

packages.redhat.com (manual / non-Konflux): use Basic Auth; [cli] can set base_url = "https://packages.redhat.com", api_root = "/api/pulp/", username, password, and domain. OAuth2 (client_id / client_secret) is also supported. For distribution pull, add cert and key paths or use username/password via --distribution-config. Konflux namespaces should use pulp-access-controller instead of ad hoc config.

Usage and API

pulp-tool --config ~/.config/pulp/cli.toml \
  --build-id my-build-123 \
  --namespace my-namespace \
  upload \
  --parent-package my-package \
  --rpm-path /path/to/rpms \
  --sbom-path /path/to/sbom.json

pulp-tool --config ~/.config/pulp/cli.toml \
  upload \
  --results-json /path/to/pulp_results.json \
  --signed-by key-id-123

pulp-tool pull \
  --artifact-location /path/to/artifacts.json \
  --transfer-dest ~/.config/pulp/cli.toml

pulp-tool --config ~/.config/pulp/cli.toml search-by --checksums <sha256>

pulp-tool --config ~/.config/pulp/cli.toml \
  update-build \
  --results-json quay.io/org/repo@sha256:… \
  --artifact-results /tekton/results/pulp-image-url,/tekton/results/pulp-image-digest \
  --oci-storage quay.io/org/repo:tag \
  --signed-by key-id-123

pulp-tool --help
pulp-tool upload --help
pulp-tool update-build --help
pulp-tool search-by --help

Full command tables, examples, and logging: docs/cli-reference.md. The upload subcommand is a compatibility alias for upload-build (preferred in new docs and examples).

from pulp_tool import PulpClient, PulpHelper
from pulp_tool.models import RepositoryRefs

client = PulpClient.create_from_config_file(path="~/.config/pulp/cli.toml")
try:
    helper = PulpHelper(client)
    repos: RepositoryRefs = helper.setup_repositories("my-build-123")

    response = client.upload_rpm_package(
        "/path/to/package.rpm",
        labels={"build_id": "my-build-123"},
        arch="x86_64",
    )
finally:
    client.close()

from pulp_tool import DistributionClient

dist = DistributionClient(cert="/path/to/cert.pem", key="/path/to/key.pem")
dist = DistributionClient(username="user", password="pass")

metadata = dist.pull_artifact("https://pulp.example.com/artifacts.json").json()
dist.pull_data(filename="pkg.rpm", file_url="...", arch="x86_64", artifact_type="rpm")

Models: RepositoryRefs, UploadContext, PullContext, ArtifactMetadata, PulpResultsDocument, PulledArtifacts.

Development

Konflux / Tekton: pulp-tool runs in RPM build (import-to-quay) and release (push-artifacts-to-storage) tasks. If you change upload, SBOM/artifact behavior, or the container image, read CLAUDE.md for contracts and regression checks; re-verify konflux-ci/rpmbuild-pipeline (task/import-to-quay.yaml) and konflux-ci/release-service-catalog (tasks/managed/push-artifacts-to-storage/). Pipelines evolve (e.g. ORAS or oras-staging/); update CLAUDE.md when upstream staging changes. Architecture overview: docs/ARCHITECTURE.md.

make install-dev          # editable install + pre-commit (+ pre-push) hooks
make format               # ruff format + ruff check --fix
make lint                 # ruff, pylint, mypy (same as CI python-lint job)
make pre-commit-ci        # all pre-commit hooks: lint + pip-audit + diff-cover + checkton
pre-commit run --all-files   # commit-stage hooks only; loop until green
make test                 # full suite + coverage (85%+ project threshold)
make test-container       # optional local Dockerfile smoke-test (Konflux Tekton builds the image on PR/push)
git fetch origin
make test-diff-coverage   # PR gate: 100% diff vs COMPARE_BRANCH (default origin/main)
make check                # lint + test

Dependency lockfile: uv.lock is generated from pyproject.toml; after changing dependencies, run make lock.

Before a PR, ensure make pre-commit-ci (or commit + pre-push pre-commit stages) and make test are green. For AI-assisted work see AGENTS.md (start with § Bootstrap), docs/ARCHITECTURE.md, and CLAUDE.md (Konflux contracts); also CONTRIBUTING.md and tests/README.md. Maintainers: release with make release-please → make release-publish → Konflux release — see docs/releasing.md. Optional AgentReady: pip install agentready && agentready assess . (.agentready-config.yaml; reports under .agentready/, gitignored).

Troubleshooting

Contributing: fork, branch, change with tests, then make test and make pre-commit-ci (or make test-diff-coverage after git fetch origin), and open a pull request.

License

Apache License 2.0. See LICENSE.