Merge pull request #259 from mkosiarc/custom-tags

Add documentation for using custom additional tags

docs/modules/ROOT/nav-how-to-guides.adoc

@@ -9,6 +9,7 @@
 *** xref:how-to-guides/proc_prefetching-dependencies-to-support-hermetic-build.adoc[Prefetching package manager dependencies for hermetic build]
 *** xref:how-to-guides/configuring-builds/proc_defining_component_relationships.adoc[Defining component relationships]
 *** xref:how-to-guides/configuring-builds/proc_preventing_redundant_rebuilds.adoc[Preventing redundant rebuilds]
+*** xref:how-to-guides/configuring-builds/proc_custom-tags.adoc[Using custom tags]
 ** Testing your application
 *** xref:how-to-guides/testing_applications/con_test-overview.adoc[Overview of {ProductName} tests]
 *** xref:how-to-guides/testing_applications/surface-level_tests.adoc[Surface-level tests]

docs/modules/ROOT/pages/how-to-guides/configuring-builds/proc_custom-tags.adoc

@@ -0,0 +1,88 @@
+:_content-type: PROCEDURE
+:troubleshooting_builds:
+
+[id="custom-tags_{context}"]
+= Using custom tags
+
+Konflux allows tagging built images with custom tags. This tagging is handled by separate *apply-tags* task. The custom tags can be configured in two ways:
+
+. <<using-konflux-label>>
+. <<using-additional-tags-parameter>>
+
+[NOTE]
+====
+These can be combined and used together
+====
+
+[[using-konflux-label]]
+== Using konflux.additional-tags image label in your Dockerfile
+
+You can specify the additional custom tags directly in your Dockerfile by using the *konflux.additional-tags* label, e.g.:
+
+----
+LABEL konflux.additional-tags="tag1"
+----
+
+If you want to specify multiple tags, they have to be separated by space or a comma, e.g.:
+
+----
+LABEL konflux.additional-tags="tag1 tag2"
+----
+
+----
+LABEL konflux.additional-tags="tag1, tag2"
+----
+
+[[using-additional-tags-parameter]]
+== Using ADDITIONAL_TAGS parameter for apply-tags task.
+You can also specify additional custom tags by using *ADDITIONAL_TAGS* array parameter for apply-tags task in your PipelineRun definition, e.g:
+
+----
+...
+- name: apply-tags
+      params:
+      - name: IMAGE
+        value: $(tasks.build-container.results.IMAGE_URL)
+      - name: ADDITIONAL_TAGS
+        value: ["tag1", "tag2"]
+      runAfter:
+      - build-container
+...
+----
+
+The array parameter ADDITIONAL_TAGS can also be specified differently:
+
+----
+...
+- name: apply-tags
+      params:
+      - name: IMAGE
+        value: $(tasks.build-container.results.IMAGE_URL)
+      - name: ADDITIONAL_TAGS
+        value:
+          - tag1
+          - tag2
+      runAfter:
+      - build-container
+...
+----
+
+[NOTE]
+====
+The provided tags can also be based on dynamic variables that are provided by Pipelines as Code, e.g.:
+
+----
+...
+- name: apply-tags
+      params:
+      - name: IMAGE
+        value: $(tasks.build-container.results.IMAGE_URL)
+      - name: ADDITIONAL_TAGS
+        value: ["pull-request-{{pull_request_number}}", "from-branch-{{source_branch}}", "{{target_branch}}"]
+      runAfter:
+      - build-container
+...
+----
+
+To see all available dynamic variables, please see the dynamic variables section in the https://pipelinesascode.com/docs/guide/authoringprs/#dynamic-variables[Pipeline as Code documentation]
+====