Applying task migrations

Konflux allows task owners to write migrations to bring pipeline changes to users. Generally, users do not need to care about how the migrations are defined and how Konflux applies migrations to their build pipelines. MintMaker applies the migrations automatically as part of the regular pull requests that update Tekton tasks. However, in case users are required to apply migrations by themselves, this document illustrates how to do that.

Apply migration with pipeline-migraiton-tool

  1. Install pipeline-migration-tool:

    Choose a release from releases page and install a specific version.

    pipx install https://github.com/konflux-ci/pipeline-migration-tool/archive/refs/tags/v0.4.2.zip

    This installs two executables in $PATH - pipeline-migration-tool and its alias, pmt. In this document, we will use pmt.

  2. Identify bundle upgrades

    If there is some migration, you can see "migration" appearing in the Notes column in the description of a Renovate update pull request. For example:

    doc mintmaker renovate update pr

    Then, check the bundle update from changes page:

               - name: name
             value: clamav-scan
           - name: bundle
-            value: quay.io/konflux-ci/tekton-catalog/task-clamav-scan:0.2@sha256:7749146f7e4fe530846f1b15c9366178ec9f44776ef1922a60d3e7e2b8c6426b
+            value: quay.io/konflux-ci/tekton-catalog/task-clamav-scan:0.3@sha256:cce2dfcc5bd6e91ee54aacdadad523b013eeae5cdaa7f6a4624b8cbcc040f439
           - name: kind
             value: task
         resolver: bundles

  3. Run command to apply migration. Convert the bundle update into upgrade data, then run CLI pmt from the Component repository root directory with the upgrade data:

    cd path/to/component-repo

pmt migrate -u '
[
    {
        "depName": "quay.io/konflux-ci/tekton-catalog/task-clamav-scan",
        "currentValue": "0.2",
        "currentDigest": "sha256:7749146f7e4fe530846f1b15c9366178ec9f44776ef1922a60d3e7e2b8c6426b",
        "newValue": "0.3",
        "newDigest": "sha256:cce2dfcc5bd6e91ee54aacdadad523b013eeae5cdaa7f6a4624b8cbcc040f439",
        "packageFile": ".tekton/<pipeline file>", (1)
        "parentDir": ".tekton",
        "depTypes": ["tekton-bundle"]
    },
    {
        "depName": "quay.io/konflux-ci/tekton-catalog/task-clamav-scan",
        "currentValue": "0.2",
        "currentDigest": "sha256:7749146f7e4fe530846f1b15c9366178ec9f44776ef1922a60d3e7e2b8c6426b",
        "newValue": "0.3",
        "newDigest": "sha256:cce2dfcc5bd6e91ee54aacdadad523b013eeae5cdaa7f6a4624b8cbcc040f439",
        "packageFile": ".tekton/<pipeline file>", (2)
        "parentDir": ".tekton",
        "depTypes": ["tekton-bundle"]
    }
    , ... (3)
]
'
    1 Replace <pipeline file> with actual file name which is under .tekton/ directory.
    2 Likewise. Specify another pipeline file.
    3 You can specify more upgrades if there are any.

    In this context, 'build pipeline' or 'pipeline file' are refering to a YAML file including a Tekton Pipeline or PipelineRun definition.

Apply migration manually

For whatever the reason, in case there is no migration delivered by the bundle update. The linked migration document should include instructions for making changes to build pipelines. When necessary, consult the linked document and follow the instructions to do manual update.

Additional resources