Defining component relationships

When a component’s repository contains a digest reference to another component’s image (for example, a Dockerfile FROM clause using sha256:…), Konflux can automatically open pull requests to keep that reference current after every successful build. To enable this, define the relationship between components using a NudgeConfig resource.

Konflux only updates image digest references. Tag-based references are not updated.

If image digests point to an architecture-specific Image Manifest, nudging updates the digest to a matching architecture. For nudging to update to an Image Index, the current digest must already point to an Image Index.

Interfaces

Nudging is implemented in the integration service, which reads a NudgeConfig resource in your namespace. You define component relationships in the CLI, as described in In the CLI.

Defining component relationships in the Konflux console is not available yet. Console support is planned; use the CLI procedure below until it is available.

In the CLI

Prerequisites:

You have completed the steps listed in the Getting started in the CLI page.

Nudge relationships are declared in a NudgeConfig resource — one per namespace, always named nudge-config. Creating or updating this resource immediately takes effect for subsequent builds.

Procedure

Create a file named nudge-config.yaml with your nudge relationships:

apiVersion: appstudio.redhat.com/v1beta2
kind: NudgeConfig
metadata:
  name: nudge-config          (1)
  namespace: <your-namespace>
spec:
  nudges:
    - from: <nudging-component>   (2)
      to: <nudged-component>      (3)

1	The name must always be `nudge-config`. There is exactly one `NudgeConfig` per namespace.
2	The component whose successful push build triggers the update.
3	The component whose repository receives the automated pull request. To define multiple relationships, add more entries under `spec.nudges`: `spec: nudges: - from: operator to: bundle - from: operator to: catalog`

Apply the resource:
```
kubectl apply -f nudge-config.yaml
```

Verification

Confirm the resource was created:

kubectl get nudgeconfig nudge-config -n <your-namespace> -o yaml

Push a commit to the nudging component. When the build completes, a pull request should appear in the nudged component’s repository containing the new image digest.

Editing relationships

To add or remove nudge relationships, edit the NudgeConfig directly and re-apply:

kubectl edit nudgeconfig nudge-config -n <your-namespace>

Removing an entry from spec.nudges stops that nudge relationship. Adding an entry takes effect on the next push build of that component.

Troubleshooting

Ensure that the existing references in the component repositories are correct.
Verify that both the from and to components exist in the namespace: kubectl get components -n <your-namespace>

Status and conditions

To check the validation state of your NudgeConfig:

kubectl get nudgeconfig nudge-config -n <your-namespace> -o yaml

The status.conditions field includes a StaleReferences condition that is set to True when one or more from or to components referenced in spec.nudges no longer exist in the namespace. Stale entries do not block valid nudges from running — only the affected relationships are inactive. Remove or update the stale entries in spec.nudges and re-apply to clear the condition.

Validation rules

The following constraints are enforced when you create or update a NudgeConfig:

from and to must be different — a component cannot nudge itself.
The same (from, to) pair cannot appear more than once.
The nudge graph must contain no cycles — for example, A→B→A is rejected.
At creation time, both from and to must refer to existing Component resources in the same namespace. After creation, if a component is deleted, the NudgeConfig is not rejected — a StaleReferences status condition is set instead (see [Status and conditions] below).
from and to values must follow Kubernetes naming conventions: lowercase alphanumeric characters and hyphens only, must start and end with an alphanumeric character, maximum 63 characters each.
spec.nudges can contain at most 360 entries.
The resource must be named nudge-config — only one NudgeConfig is allowed per namespace.

What is nudged

Nudging is triggered only when a push pipeline run finishes successfully (including re-runs). Builds triggered by GitHub merge queue branches (gh-readonly-queue/*) do not trigger nudging.

When component1 nudges component2, the following image references are updated in `component2’s repository:

The output image from component1’s push pipeline run (the `output-image param, for example quay.io/user-tenant/user-image).
Images from distribution repositories defined in a ReleasePlanAdmission, if the admission includes a mapping for the nudging component:
```
spec:
  data:
    mapping:
      components:
        - name: component1
          repository: quay.io/some-org/released-image
```
In this case both quay.io/user-tenant/user-image and quay.io/some-org/released-image are updated.

A nudging pull request is created in a branch named: konflux/component-updates/NUDGED_COMPONENT-NUDGING_COMPONENT

If you nudge multiple components that share the same repository and branch, add the following annotation to the nudging (source) component to consolidate the updates into a single pull request:

metadata:
  annotations:
    build.appstudio.openshift.io/build-nudge-simple-branch: 'true'

Controlling which files are scanned

By default, Konflux scans Dockerfiles, Containerfiles, and YAML files for image digest references. Override this per pipeline run with an annotation on the push PipelineRun definition:

metadata:
  annotations:
    build.appstudio.openshift.io/build-nudge-files: ".*Dockerfile.*, .*.yaml, .*Containerfile.*"

This annotation supports a comma-separated list of regex or glob patterns.

Customizing nudging PRs

Nudging uses Renovate to open pull requests. You can customize its behavior with a ConfigMap in your namespace.

The following options are configurable:

automerge
automergeType
commitMessagePrefix
commitMessageSuffix
fileMatch (comma-separated)
ignoreTests
platformAutomerge
gitLabIgnoreApprovals
automergeSchedule (semicolon-separated)
labels (comma-separated)

There are two scopes:

Namespace-wide: Create a ConfigMap named namespace-wide-nudging-renovate-config. This applies to all nudged components in the namespace unless a component-specific ConfigMap exists.
Per-component: Create a ConfigMap with any name and add the annotation build.appstudio.openshift.io/nudge_renovate_config_map: <configmap-name> to the nudged component.

All values must be strings. For boolean options, use "true" or "false".

platformAutomerge is enabled by default in Renovate. If you do not set it explicitly in your ConfigMap, auto-merge via the platform (for example, GitHub auto-merge) is already active for nudging PRs.

labels values are appended to the default konflux-nudge label that Konflux always sets on nudging PRs. They do not replace it.

ConfigMap example

apiVersion: v1
kind: ConfigMap
metadata:
  name: namespace-wide-nudging-renovate-config
  namespace: <your-namespace>
data:
  automerge: "true"
  automergeType: "pr"
  commitMessagePrefix: "custom namespace prefix message"
  commitMessageSuffix: "custom namespace suffix message"
  fileMatch: ".*Dockerfile.*, .*.yaml, .*Containerfile.*"
  ignoreTests: "true"
  gitLabIgnoreApprovals: "true"
  platformAutomerge: "true"
  # automergeSchedule: "* 22-23,0-4 * * *; * * * * 0,6"
  labels: "customLabel1, customLabel2"