Pulp Tool

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

Overview: Setup · Usage and API · Development · License

Setup

Clone and install:

git clone https://github.com/konflux/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 with base_url, api_root, OAuth or Basic Auth fields, domain, verify_ssl, format, dry_run, timeout, verbose, and optionally correlation_id for X-Correlation-ID (or set PULP_TOOL_CORRELATION_ID). See CONTRIBUTING.md and pulp-tool --help for defaults.

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: use Basic Auth; [cli] can set base_url = "https://packages.redhat.com", api_root = "/api/pulp/", username, password, domain, verify_ssl. OAuth2 (client_id / client_secret) is also supported. For distribution pull, add cert and key paths for pull/transfer operations.

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 --help
pulp-tool upload --help
pulp-tool search-by --help

Full command tables, examples, and logging: docs/cli-reference.md.

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, PulpResultsModel, 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 install
make format               # black pulp_tool/ tests/
make lint                 # black --check, flake8, pylint, mypy
pre-commit run --all-files   # loop: fix reported issues, re-run until fully 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: requirements.txt is generated from requirements.in; after changing dependencies in pyproject.toml, run make lock.

Before a PR, ensure pre-commit has passed and, after git fetch origin, make test-diff-coverage is 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. Optional AgentReady: pip install agentready && agentready assess . (.agentready-config.yaml; reports under .agentready/, gitignored).

Troubleshooting

Issue	Check
Command not found	pip install -e . or pip install pulp-tool
Authentication errors	Verify ~/.config/pulp/cli.toml credentials
SSL/TLS errors	Verify cert/key paths and permissions
Permission denied	Check file permissions on artifacts and key

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

License

Apache License 2.0. See LICENSE.