// Use when adding, updating, or troubleshooting RPM or artifact dependencies for the hermetic build. Covers rpms.in.yaml, rpms.lock.yaml, artifacts.lock.yaml, epel.repo, Cachi2 prefetching, and the Dockerfile install step.
Use when preparing a pull request for review or when CI checks fail. Checklist covering commit conventions, Dockerfile linting, formatting rules, security, and all CI checks that run on PRs.
Use when a Tekton build pipeline fails, when you need to understand task ordering or resource requirements, or when debugging security scan failures. Covers PR and push pipeline differences, the fetch-db-data step, and all security scan tasks.
Use when troubleshooting the automated daily vulnerability database update, understanding the build trigger flow, or debugging fetch-db-data failures. Covers the GitHub Actions cron, push pipeline, matcher.db lifecycle, and manual triggering.
| name | hermetic-build-deps |
| description | Use when adding, updating, or troubleshooting RPM or artifact dependencies for the hermetic build. Covers rpms.in.yaml, rpms.lock.yaml, artifacts.lock.yaml, epel.repo, Cachi2 prefetching, and the Dockerfile install step. |
This repo uses Konflux hermetic builds — the build-container task runs with no network access. All external dependencies (RPMs, GPG keys) must be prefetched by Cachi2 during the prefetch-dependencies task and made available offline. Four files control this system and must stay in sync.
| File | Purpose | Format |
|---|---|---|
rpms.in.yaml | Declares which packages to install | packages: [jq] + repo config pointer |
rpms.lock.yaml | Pinned RPM versions, repos, checksums | Auto-generated lock file |
artifacts.lock.yaml | Pinned generic artifacts (GPG keys, individual RPMs) | Manual checksums for non-repo downloads |
epel.repo | EPEL 8 yum/dnf repository configuration | Standard repo file format |
rpms.in.yaml ─── declares "I need jq" + points to epel.repo
│
├─ rpms.lock.yaml ─── resolves jq to exact version + checksum from repos
│
└─ epel.repo ─── provides the EPEL 8 metalink URL for resolution
artifacts.lock.yaml ─── pins the EPEL GPG key + individual RPM downloads
(these are fetched as "generic" artifacts by Cachi2)
The prefetch-input parameter tells Cachi2 what to prefetch:
prefetch-input: '[{"type": "rpm", "path": "."}, {"type": "generic", "path": "."}]'
type: rpm — reads rpms.in.yaml → resolves via rpms.lock.yaml → downloads RPMstype: generic — reads artifacts.lock.yaml → downloads listed artifacts by URL + checksumPrefetched artifacts land in /cachi2/output/deps/:
RUN rpm --import /cachi2/output/deps/generic/RPM-GPG-KEY-EPEL-8 && \
microdnf -y --setopt=tsflags=nodocs install \
--setopt=install_weak_deps=0 \
jq-1.6-11.el8_10 && \
microdnf clean all
Key points:
microdnf install uses exact version (jq-1.6-11.el8_10) matching rpms.lock.yaml--setopt=tsflags=nodocs and --setopt=install_weak_deps=0 minimize image size| Package | Pinned Version |
|---|---|
| jq | 1.6-11.el8_10 |
| Artifact | Source |
|---|---|
| RPM-GPG-KEY-EPEL-8 | dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-8 |
| jq-1.6-11.el8_10.x86_64.rpm | cdn-ubi.redhat.com (UBI 8 appstream) |
| oniguruma-6.8.2-3.el8.x86_64.rpm | cdn-ubi.redhat.com (UBI 8 appstream, jq dependency) |
Add the package name to rpms.in.yaml:
packages: [jq, newpackage]
Regenerate the lock file using rpm-lockfile-prototype:
rpm-lockfile-prototype --image <BASE_IMAGE> rpms.in.yaml
This resolves packages against the base image, producing rpms.lock.yaml with exact versions and checksums. See Konflux docs for details.
If the RPM or its dependencies need to be pinned as generic artifacts, add entries to artifacts.lock.yaml with the download URL and SHA-256 checksum
Update the Dockerfile to install the new package with its exact version:
microdnf -y --setopt=tsflags=nodocs install \
--setopt=install_weak_deps=0 \
jq-1.6-11.el8_10 \
newpackage-x.y-z.el8
Keep it as a single RUN layer to minimize image size
rpms.lock.yaml (or regenerate with Cachi2)artifacts.lock.yaml if the RPM is also listed theremicrodnf install command| Problem | Fix |
|---|---|
| prefetch-dependencies fails with checksum mismatch | Checksums in artifacts.lock.yaml or rpms.lock.yaml are stale — regenerate or update |
| Build fails with "package not found" | RPM version in Dockerfile doesn't match rpms.lock.yaml pinned version |
| GPG key import fails | artifacts.lock.yaml checksum for RPM-GPG-KEY-EPEL-8 is wrong or key URL changed |
| New package not installed | Added to rpms.in.yaml but didn't regenerate rpms.lock.yaml |
| Transitive dependency missing | Add the dependency RPM to artifacts.lock.yaml as a generic artifact (like oniguruma for jq) |
| Hermetic build fails with network error | Verify all deps are in lock files — hermetic builds have no network access |