Add OCI label injection #39

New Issue

2026-01-03T23:45:11Z

KofTwentyTwo commented

2026-01-03 23:45:11 +00:00

(Migrated from github.com)

Part of #13

User Story

As a developer, I want OCI labels automatically added to my images so that I can trace builds back to source code and identify image metadata.

Design

Standard OCI Labels

Following OCI Image Spec Annotations:

Label	Value Source
`org.opencontainers.image.title`	pom.xml artifactId
`org.opencontainers.image.version`	pom.xml version
`org.opencontainers.image.revision`	git commit SHA
`org.opencontainers.image.source`	git remote URL
`org.opencontainers.image.created`	Build timestamp (ISO 8601)
`org.opencontainers.image.authors`	pom.xml developers
`org.opencontainers.image.vendor`	pom.xml organization
`org.opencontainers.image.licenses`	pom.xml licenses
`org.opencontainers.image.description`	pom.xml description

QRun Custom Labels

Label	Value
`io.qrun.app.name`	Application name
`io.qrun.app.module`	QQQ module name
`io.qrun.build.tool`	`qctl`
`io.qrun.build.version`	qctl version

Configuration

In qrun.yaml:

package:
  labels:
    custom.label.one: "value1"
    custom.label.two: "value2"
  
  # Disable auto-labels
  autoLabels: false

Inspection

# View labels after build
docker inspect myapp:v1 --format '{{json .Config.Labels}}' | jq

# Or with skopeo
skopeo inspect docker://myapp:v1 | jq '.Labels'

Files to Create/Modify

File	Action	Description
`OciLabels.java`	Create	Label constants and builder
`LabelCollector.java`	Create	Collects labels from various sources
`GitInfoProvider.java`	Create	Extracts git commit/remote
`PomInfoProvider.java`	Create	Extracts Maven POM metadata
`JibBuilder.java`	Modify	Apply labels to image

Implementation Tasks

Create OciLabels enum with standard label names
Create LabelCollector class
Implement GitInfoProvider for commit SHA and remote URL
Implement PomInfoProvider for artifact metadata
Extract version from pom.xml
Extract description from pom.xml
Extract developers/organization from pom.xml
Generate ISO 8601 timestamp for created
Add qrun-specific labels
Support custom labels from qrun.yaml
Support autoLabels: false to disable
Apply labels via Jib API
Add unit tests for label collection
Document all labels in README

Acceptance Criteria

All standard OCI labels present in image
Git commit SHA included as revision
Git remote URL included as source
Version matches pom.xml
Custom labels from config applied
autoLabels: false disables auto-labels
Labels visible via docker inspect
Labels visible via skopeo inspect

Part of #13 ## User Story As a **developer**, I want OCI labels automatically added to my images so that I can trace builds back to source code and identify image metadata. ## Design ### Standard OCI Labels Following [OCI Image Spec Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md): | Label | Value Source | |-------|--------------| | `org.opencontainers.image.title` | pom.xml artifactId | | `org.opencontainers.image.version` | pom.xml version | | `org.opencontainers.image.revision` | git commit SHA | | `org.opencontainers.image.source` | git remote URL | | `org.opencontainers.image.created` | Build timestamp (ISO 8601) | | `org.opencontainers.image.authors` | pom.xml developers | | `org.opencontainers.image.vendor` | pom.xml organization | | `org.opencontainers.image.licenses` | pom.xml licenses | | `org.opencontainers.image.description` | pom.xml description | ### QRun Custom Labels | Label | Value | |-------|-------| | `io.qrun.app.name` | Application name | | `io.qrun.app.module` | QQQ module name | | `io.qrun.build.tool` | `qctl` | | `io.qrun.build.version` | qctl version | ### Configuration In `qrun.yaml`: ```yaml package: labels: custom.label.one: "value1" custom.label.two: "value2" # Disable auto-labels autoLabels: false ``` ### Inspection ```bash # View labels after build docker inspect myapp:v1 --format '{{json .Config.Labels}}' | jq # Or with skopeo skopeo inspect docker://myapp:v1 | jq '.Labels' ``` ## Files to Create/Modify | File | Action | Description | |------|--------|-------------| | `OciLabels.java` | Create | Label constants and builder | | `LabelCollector.java` | Create | Collects labels from various sources | | `GitInfoProvider.java` | Create | Extracts git commit/remote | | `PomInfoProvider.java` | Create | Extracts Maven POM metadata | | `JibBuilder.java` | Modify | Apply labels to image | ## Implementation Tasks - [ ] Create `OciLabels` enum with standard label names - [ ] Create `LabelCollector` class - [ ] Implement `GitInfoProvider` for commit SHA and remote URL - [ ] Implement `PomInfoProvider` for artifact metadata - [ ] Extract version from pom.xml - [ ] Extract description from pom.xml - [ ] Extract developers/organization from pom.xml - [ ] Generate ISO 8601 timestamp for `created` - [ ] Add qrun-specific labels - [ ] Support custom labels from `qrun.yaml` - [ ] Support `autoLabels: false` to disable - [ ] Apply labels via Jib API - [ ] Add unit tests for label collection - [ ] Document all labels in README ## Acceptance Criteria - [ ] All standard OCI labels present in image - [ ] Git commit SHA included as revision - [ ] Git remote URL included as source - [ ] Version matches pom.xml - [ ] Custom labels from config applied - [ ] `autoLabels: false` disables auto-labels - [ ] Labels visible via `docker inspect` - [ ] Labels visible via `skopeo inspect`

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#39