Running Build Pipelines

Konflux uses Pipelines as Code (PaC) to run pipelines from webhook events. When you create a Component, Konflux submits a merge request to automatically run build pipelines before merge ("pre-merge") and after merge ("post-merge"). Developers often need to retrigger these builds for various reasons, such as an unexpected failure or a missed webhook event.

See also Retriggering integration tests.

Running Builds Pre-Merge

Trigging a pre-merge build on a pull request

Prerequsite

  • You have created a Component in Konflux for the desired source code repository and branch.

  • You have merged the Konflux-generated build pipelines into your source code repository.

Procedure

  1. Submit a merge/pull request against the component’s target branch. The process to do this may vary depending on the source code provider:

    1. If your source code is hosted on GitHub or GitHub Enterprise, submit a pull request against the component’s target branch. You can do this from a different branch on the source code repository, or from your own personal fork.

    2. If your source code is hosted on GitLab, your code changes must be on the same repository as the target branch. Personal forks are currently not supported - see Red Hat issue SRVKP-7590 for more information.

  2. The build pipeline should execute if your user account has been granted permissions to run PaC piplines. If your account does not have these permissions, a project maintainer or other user must add the comment /ok-to-test to start the build pipeline.

    There are rules that govern who can execute the /ok-to-test comment. Please see Running the PipelineRun for more information.

Retriggering a pre-merge build on a pull request

Prerequisite

  • You have a build pipeline run on a pull request that has failed, and you want to re-run the build without pushing a new commit.

Procedure

  1. Add a comment to the pull request with the text /retest to trigger a new build.

    The pipeline run should start executing in the Activity > Pipeline runs tab and in the pull request.

    There are rules that govern who can execute the /retest comment. They follow the same requirements as determining whether a submitter is allowed to run the PipelineRun. Please see Running the PipelineRun.
    For additional options, refer to the Pipelines as Code documentation.

Running Builds Post-Merge

Triggering a post-merge build

Prerequsite

  • You have created a Component in Konflux for the desired source code repository and branch.

  • You have merged the Konflux-generated build pipelines into your source code repository.

Procedure

  1. Builds should automatically be triggered when code is merged in the component’s branch.

  2. If a build is not triggered in a timely fashion, check that the post-merge pipeline is configured properly. The PipelineRun YAML file should have the following annotations:

    ---
metadata:
  annotations:
      pipelinesascode.tekton.dev/on-target-branch: "[main]" # or other branch for the component
      pipelinesascode.tekton.dev/on-event: "[push]"
---

See Matching Events with Pipelines as Code for more information.

Retriggering a post-merge build from from GitHub

Prerequisite

  • You have already merged a pull request, but the subsequent build failed, prompting a need for retriggering.

Procedure

  1. On the GitHub UI, navigate to the latest commit on your branch that that you want to rebuild.

  2. Comment /retest on the commit. If the commit is not on the default branch, use /retest branch:<branch-name>

    All pipeline runs associated with that commit should resume in the Activity > Pipeline runs tab.

    This procedure only works to retrigger the build pipeline for the latest commit on the branch.
    For instructions on how to retrigger only individual build pipelines, not all, see pipelinesascode documentation.
    If you only want to retrigger the integration tests, see retriggering integration tests.
    There are rules that govern who can execute the /retest comment. They follow the same requirements as determining whether a submitter is allowed to run the PipelineRun. Please see Running the PipelineRun.

Retriggering a post-merge build from your main branch from the UI

Prerequisite

  • You have already merged a pull request, but the subsequent build failed, prompting a need for retriggering.

  • You didn’t rename push pipeline run name, and it is in format component_name + '-on-push'

Procedure

In the console, complete the following steps to retrigger the build pipeline:

  1. Navigate to the Activity > Pipeline runs tab.

  2. Identify the pipeline run that you want to retrigger.

  3. Select the three dots on the right side of the table.

  4. Select the Rerun action.

    The pipeline run should resume in the Activity > Pipeline runs tab.

Retriggering a post-merge build from your main branch from the API

Prerequisite

  • You have already merged a pull request, but the subsequent build failed, prompting a need for retriggering.

  • You didn’t rename push pipeline run name, and it is in format component_name + '-on-push'

  • You have CLI access to Konflux. For information on obtaining CLI access, refer to Getting started in CLI

Procedure

  1. Identify the Component whose pipeline requires rerun.

  2. Use the following command to annotate the Component, triggering a new build:

    $ kubectl annotate components/[component name] build.appstudio.openshift.io/request=trigger-pac-build

  3. The build is re-triggered automatically.

    $ tkn pipelinerun list

[Example Output]
NAME                            STARTED         DURATION   STATUS
your-component-jfrdb            4 seconds ago   ---        Running