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.

In the UI

Procedure

To define the relationships between components in a tenant namespace, complete the following steps in the Konflux UI:

Currently, applications with only one component do not have the option to define relationships in the UI. To achieve the same result for single-component applications, define the relationship in the CLI.

Navigate to your application.
On any tab, use the Actions drop-down menu to select Define component relationships.
1. Alternatively, go to the Components tab and select Define component relationships.
In the Component relationships window, select one component from the Select a component drop-down menu.

Select Nudges or Is nudged by, depending on the relationship you want to define.

Component A nudges Component B (or Component B is nudged by Component A) if Component B contains a reference, by image digest, to a build of Component A. After successful push builds of Component A, nudging updates the image digest that Component B references.

Use the remaining drop-down menu to choose the related components.
To define multiple relationships, select Add another component relationship.
Select Save relationships.

Verification

Go to the Components tab, select a component, and scroll to Show related components.
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.

Troubleshooting

If you do not see the relationship, redefine it and make sure to select Save relationships.
Ensure that the existing references in the component repositories are correct.

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>

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.
Both from and to must be names of existing Component resources in the same namespace.
spec.nudges can contain at most 256 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).

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-component-update-NUDGING_COMPONENT

If you nudge multiple components that share the same repository and branch, add the following annotation to all affected components to consolidate 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".

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"