konflux-ci · arewm · Mar 14, 2025 · Mar 14, 2025
@@ -3,25 +3,25 @@
 *   @konflux-ci/docs
 
 # installation
-/modules/ROOT/pages/advanced-how-tos/installing/   @konflux-ci/installer-maintainers
+/modules/ROOT/pages/installing/   @konflux-ci/installer-maintainers
 
 # build
-/modules/ROOT/pages/how-tos/configuring/           @konflux-ci/build-maintainers
-/modules/ROOT/partials/how-tos/configuring/        @konflux-ci/build-maintainers
+/modules/ROOT/pages/building/           @konflux-ci/build-maintainers
+/modules/ROOT/partials/building/        @konflux-ci/build-maintainers
 
 # integration
-/modules/ROOT/pages/how-tos/testing/               @konflux-ci/integration-service-maintainers
+/modules/ROOT/pages/testing/               @konflux-ci/integration-service-maintainers
 
 # release
-/modules/ROOT/pages/advanced-how-tos/releasing                                @konflux-ci/release-service-maintainers
-/modules/ROOT/pages/advanced-how-tos/testing-releasing-single-component.adoc  @konflux-ci/release-service-maintainers
+/modules/ROOT/pages/releasing                                @konflux-ci/release-service-maintainers
+/modules/ROOT/pages/testing-releasing-single-component.adoc  @konflux-ci/release-service-maintainers
 
 # Conforma
-/modules/ROOT/pages/advanced-how-tos/managing-compliance-with-ec       @konflux-ci/ec
-/modules/ROOT/pages/advanced-how-tos/using-trusted-artifacts.adoc      @konflux-ci/ec
+/modules/ROOT/pages/managing-compliance-with-ec       @konflux-ci/ec
+/modules/ROOT/pages/using-trusted-artifacts.adoc      @konflux-ci/ec
 
 
 # find a team to own this
 
-/modules/ROOT/pages/how-tos/metadata/              @ralphbean @arewm
-/modules/ROOT/pages/how-tos/workflows/             @ralphbean @arewm
+/modules/ROOT/pages/metadata/              @ralphbean @arewm
+/modules/ROOT/pages/patterns/             @ralphbean @arewm
@@ -4,8 +4,14 @@ title: Konflux-CI
 version: ~
 nav:
 - modules/ROOT/pages/getting-started/_nav.adoc
-- modules/ROOT/pages/how-tos/_nav.adoc
-- modules/ROOT/pages/advanced-how-tos/_nav.adoc
+- modules/ROOT/pages/end-to-end/_nav.adoc
+- modules/ROOT/pages/building/_nav.adoc
+- modules/ROOT/pages/testing/_nav.adoc
+- modules/ROOT/pages/metadata/_nav.adoc
+- modules/ROOT/pages/managing-compliance-with-ec/_nav.adoc
+- modules/ROOT/pages/releasing/_nav.adoc
+- modules/ROOT/pages/patterns/_nav.adoc
+- modules/ROOT/pages/installing/_nav.adoc
 - modules/ROOT/pages/troubleshooting/_nav.adoc
 - modules/ROOT/pages/glossary/_nav.adoc
 - modules/ROOT/pages/reference/_nav.adoc

@@ -0,0 +1,18 @@
+** xref:building/index.adoc[Building]
+*** xref:building/creating.adoc[Creating applications and components]
+*** xref:building/deleting.adoc[Deleting applications and components]
+*** xref:building/customizing-the-build.adoc[Customizing the build pipeline]
+*** xref:building/creating-secrets.adoc[Creating secrets for your builds]
+*** xref:building/configuration-as-code.adoc[Configuration as code]
+*** xref:building/using-trusted-artifacts.adoc[Using trusted artifacts]
+*** xref:building/hermetic-builds.adoc[Enabling hermetic builds]
+*** xref:building/prefetching-dependencies.adoc[Prefetching package manager dependencies]
+*** xref:building/component-nudges.adoc[Defining component relationships]
+*** xref:building/rerunning.adoc[Retriggering build pipelines]
+*** xref:building/redundant-rebuilds.adoc[Preventing redundant rebuilds]
+*** xref:building/build-with-args.adoc[Passing buildah arguments]
+*** xref:building/custom-tags.adoc[Using custom tags]
+*** xref:building/labels-and-annotations.adoc[Using labels and annotations]
+*** xref:building/overriding-compute-resources.adoc[Overriding compute resources]
+*** xref:building/activation-keys-subscription.adoc[Using Red Hat subscription content]
+*** xref:building/reconfiguring-build-pipeline.adoc[Reconfiguring the build pipeline]
@@ -4,9 +4,9 @@ When you build your pipeline, you might want to add tasks that require **secrets
 
 Secrets can be categorized depending on when they need to be added.
 
-. Before a component is added. If a secret is needed to access the source control platform like xref:/how-tos/configuring/creating-secrets.adoc#creating-source-control-secrets[GitLab], you must create a secret before you create the component.
-. Before a build succeeds. Some artifact build tasks need specific secrets to be able to pull all of the content to include in the final artifact. For example, you can add secrets for xref:/how-tos/configuring/creating-secrets.adoc#creating-registry-pull-secrets[container registries] after you create the component but they must be provided before a successful build can occur.
-. After a component has been onboarded. These secrets are often used in tasks. The tasks included in the {ProductName} pipelines will not fail if a secret is not created properly. Instead, the task will just not run the code like with xref:/how-tos/configuring/creating-secrets.adoc#creating-task-input-secrets[snyk].
+. Before a component is added. If a secret is needed to access the source control platform like xref:/building/creating-secrets.adoc#creating-source-control-secrets[GitLab], you must create a secret before you create the component.
+. Before a build succeeds. Some artifact build tasks need specific secrets to be able to pull all of the content to include in the final artifact. For example, you can add secrets for xref:/building/creating-secrets.adoc#creating-registry-pull-secrets[container registries] after you create the component but they must be provided before a successful build can occur.
+. After a component has been onboarded. These secrets are often used in tasks. The tasks included in the {ProductName} pipelines will not fail if a secret is not created properly. Instead, the task will just not run the code like with xref:/building/creating-secrets.adoc#creating-task-input-secrets[snyk].
 
 == Creating task input secrets
 
@@ -32,10 +32,10 @@ NOTE: One such task is the link:https://github.com/konflux-ci/build-definitions/
 
 === Notable task input secrets
 
-* xref:/how-tos/configuring/activation-keys-subscription.adoc#adding-activation-keys-to-the-workspace[activation-key]
-* xref:/how-tos/configuring/prefetching-dependencies.adoc#creating-the-netrc-secret[netrc]
-* xref:/how-tos/testing/build/snyk.adoc[snyk-secret]
-* xref:/how-tos/testing/integration/third-parties/testing-farm.adoc[testing-farm-secret]
+* xref:/building/activation-keys-subscription.adoc#adding-activation-keys-to-the-workspace[activation-key]
+* xref:/building/prefetching-dependencies.adoc#creating-the-netrc-secret[netrc]
+* xref:/testing/build/snyk.adoc[snyk-secret]
+* xref:/testing/integration/third-parties/testing-farm.adoc[testing-farm-secret]
 
 == Creating registry pull secrets
 
@@ -214,7 +214,7 @@ stringData:
 * If you upload a GitLab access token to a workspace, {ProductName} won’t use the global GitHub application when accessing GitHub repositories.
 ====
 
-include::ROOT:partial$how-tos/configuring/{context}-secrets-external-vault.adoc[]
+include::ROOT:partial$building/{context}-secrets-external-vault.adoc[]
 
 == Additional resources
 

@@ -4,13 +4,13 @@
 
 {ProductName} supports two methods for creating applications and components.
 
-Before being able to onboard a component to {ProductName}, you will need to ensure that the instance has appropriate access to the git repository. This means either installing your organization’s {ProductName} GitHub App on the source code repository or xref:/how-tos/configuring/creating-secrets.adoc#creating-source-control-secrets[create a secret] to enable access to a GitLab repository.
+Before being able to onboard a component to {ProductName}, you will need to ensure that the instance has appropriate access to the git repository. This means either installing your organization’s {ProductName} GitHub App on the source code repository or xref:/building/creating-secrets.adoc#creating-source-control-secrets[create a secret] to enable access to a GitLab repository.
 
 === With the UI
 .Prerequisites:
 
-* xref:/advanced-how-tos/installing/enabling-builds.adoc[Enabled] build pipelines for your instance of {ProductName}.
-* xref:/advanced-how-tos/installing/enabling-builds.adoc#enable-image-controller[Enabled] image controller for your instance of {ProductName}.
+* xref:/installing/enabling-builds.adoc[Enabled] build pipelines for your instance of {ProductName}.
+* xref:/installing/enabling-builds.adoc#enable-image-controller[Enabled] image controller for your instance of {ProductName}.
 
 ==== Create initial Application and Component
 .*Procedures*
@@ -20,19 +20,19 @@ Before being able to onboard a component to {ProductName}, you will need to ensu
 . Enter a name for the application
 . Click the *Add a component* button.
 +
-NOTE: For *Gitlab* provider, make sure to xref:/how-tos/configuring/creating-secrets.adoc#creating-source-control-secrets[create a source control secret] before creating the component.
+NOTE: For *Gitlab* provider, make sure to xref:/building/creating-secrets.adoc#creating-source-control-secrets[create a source control secret] before creating the component.
   . Enter the URL for the git repository.
   . (Optional) After clicking out of the repository URL, expand the *Show advanced Git options*.
     . Enter the branch name to the *Git reference* dialogue.
     . Enter the path to the context directory if the build context is contained somewhere other than the repository root.
   . Enter the path to the Dockerfile within the git repository. This will be the path within the context directory.
   . (Optional) Change the component name if desired.
   . (Optional) Click on the *Pipeline* drop down box and select the desired pipeline to configure your component with.
-  . (Optional) Click on *Add secret* to add a secret which will be needed for the component build. See xref:/how-tos/configuring/creating-secrets.adoc[creating secrets] for more information.
+  . (Optional) Click on *Add secret* to add a secret which will be needed for the component build. See xref:/building/creating-secrets.adoc[creating secrets] for more information.
 . Click *Create application*.
 
 +
-NOTE: GitHub and GitLab are supported source control providers. GitLab support requires the configuration of xref:/how-tos/configuring/creating-secrets.adoc#creating-source-control-secrets[source control secrets].
+NOTE: GitHub and GitLab are supported source control providers. GitLab support requires the configuration of xref:/building/creating-secrets.adoc#creating-source-control-secrets[source control secrets].
 
 ==== Create additional Components in an Application
 
@@ -48,7 +48,7 @@ NOTE: GitHub and GitLab are supported source control providers. GitLab support r
 
 .Prerequisites:
 
-* xref:/advanced-how-tos/installing/enabling-builds.adoc[Enabled] build pipelines for your instance of {ProductName}.
+* xref:/installing/enabling-builds.adoc[Enabled] build pipelines for your instance of {ProductName}.
 * link:https://kubernetes.io/docs/tasks/tools/[kubectl] CLI tool
 * You have completed the steps listed in the xref:/getting-started/cli.adoc[Getting started in the CLI] page.
 

@@ -174,7 +174,7 @@ An example of a custom task added to the pipeline that sends a slack notificatio
 
 == Preventing issues with the Enterprise Contract
 
-Custom Tasks may need access to data from other Tasks. However, in order to not break the chain of trust in a build Pipeline, there are restrictions in modifying such data. For example, a custom Task should not be allowed to modify the component's source code. If you are using the Enterprise Contract (EC) to verify your builds, introducing a custom Task may violate the link:https://enterprisecontract.dev/docs/ec-policies/release_policy.html#trusted_task__trusted[Trusted Tasks] rule. See xref:advanced-how-tos/using-trusted-artifacts.adoc[Trusted Artifacts] for how to safely allow share data between Tasks.
+Custom Tasks may need access to data from other Tasks. However, in order to not break the chain of trust in a build Pipeline, there are restrictions in modifying such data. For example, a custom Task should not be allowed to modify the component's source code. If you are using the Enterprise Contract (EC) to verify your builds, introducing a custom Task may violate the link:https://enterprisecontract.dev/docs/ec-policies/release_policy.html#trusted_task__trusted[Trusted Tasks] rule. See xref:./using-trusted-artifacts.adoc[Trusted Artifacts] for how to safely allow share data between Tasks.
 
 == Exchanging the build pipeline build task with higher memory limits
 

@@ -42,4 +42,4 @@ kubectl delete application/<the-application-name>
 ----
 
 == Additional resources
-* To create your first application, refer to xref:/how-tos/creating.adoc[Creating applications and components].
+* To create your first application, refer to xref:/building/creating.adoc[Creating applications and components].
@@ -17,7 +17,7 @@ spec:
 
 [IMPORTANT]
 ====
-* Hermetic builds disable network access, so a build with dependencies outside of its Git repository--including supported languages--might fail. To prevent this, or to pull in dependencies from a package manager for one of the xref:how-tos/configuring/prefetching-dependencies.adoc#supported-languages[supported languages], follow the instructions in xref:ROOT:how-tos/configuring/prefetching-dependencies.adoc[Prefetching the package manager dependencies for the hermetic build].
+* Hermetic builds disable network access, so a build with dependencies outside of its Git repository--including supported languages--might fail. To prevent this, or to pull in dependencies from a package manager for one of the xref:building/prefetching-dependencies.adoc#supported-languages[supported languages], follow the instructions in xref:ROOT:building/prefetching-dependencies.adoc[Prefetching the package manager dependencies for the hermetic build].
 +
 Similarly, with a link:https://github.com/konflux-ci/build-definitions/blob/main/task/buildah/0.1/buildah.yaml[Buildah] task for a non-Java application, when you set the `*hermetic*` parameter to `true`, you’re isolating the build from the network, which restricts it to building only from dependencies listed in your Git repository. 
 

@@ -1,9 +1,9 @@
 = Configuring your builds
 
-When creating a component, {ProductName} will push a Tekton PipelineRun to your component's source repository. This pipeline is yours to customize as needed for building your component and Tekton Chains will record the customizations in a detailed signed in-toto provenance attestation. This provenance enables Enterprise Contract to xref:/advanced-how-tos/managing-compliance-with-ec/index.adoc[manage compliance] to ensure the artifact's integrity and compliance with specific policies.
+When creating a component, {ProductName} will push a Tekton PipelineRun to your component's source repository. This pipeline is yours to customize as needed for building your component and Tekton Chains will record the customizations in a detailed signed in-toto provenance attestation. This provenance enables Enterprise Contract to xref:/managing-compliance-with-ec/index.adoc[manage compliance] to ensure the artifact's integrity and compliance with specific policies.
 
 == Additional resources [[additional-resources]]
 
-* The sample pipelines that you can initially configure your components with depend on the {ProductName} deployment. This might include the pipelines provided by xref:/advanced-how-tos/installing/enabling-builds.adoc#available-pipelines[{ProductName}] or other additional pipelines.
-* If you want to change the configured pipeline for your component after it is onboarded, see xref:/how-tos/configuring/reconfiguring-build-pipeline.adoc#changing-pipelines[reconfiguring the build pipeline].
+* The sample pipelines that you can initially configure your components with depend on the {ProductName} deployment. This might include the pipelines provided by xref:/installing/enabling-builds.adoc#available-pipelines[{ProductName}] or other additional pipelines.
+* If you want to change the configured pipeline for your component after it is onboarded, see xref:/building/reconfiguring-build-pipeline.adoc#changing-pipelines[reconfiguring the build pipeline].
 * Since the Tekton PipelineRuns use link:https://pipelinesascode.com[Pipelines as Code] to trigger the jobs on the cluster, you can also use any of the link:https://pipelinesascode.com/docs/guide/authoringprs/#default-parameters[default parameters] in the PipelineRuns in your git repositories.
@@ -2,7 +2,7 @@
 
 In {ProductName}, you can run a hermetic build by restricting network access to the build, but without network a build can’t fetch component dependencies from a repository and might fail. To avoid that, {ProductName} can prefetch dependencies for your hermetic builds using link:https://github.com/containerbuildsystem/cachi2/blob/main/README.md[Cachi2].
 
-For every build, Cachi2 generates a software bill of materials (SBOM) where all dependencies are properly declared and pinned to specific versions. Also, Cachi2 ensures that arbitrary code is never executed during the prefetch, meaning, for example, that the build doesn’t pull any undeclared dependencies. Such measures result in very accurate SBOMs and improve the build reproducibility. For more information about SBOMs, see xref:/how-tos/metadata/sboms.adoc[Inspecting SBOMs].
+For every build, Cachi2 generates a software bill of materials (SBOM) where all dependencies are properly declared and pinned to specific versions. Also, Cachi2 ensures that arbitrary code is never executed during the prefetch, meaning, for example, that the build doesn’t pull any undeclared dependencies. Such measures result in very accurate SBOMs and improve the build reproducibility. For more information about SBOMs, see xref:/metadata/sboms.adoc[Inspecting SBOMs].
 
 [#available-package-managers]
 .Available package managers
@@ -343,7 +343,7 @@ For example, it is useful for:
 To create a netrc Secret for use in your pipelines:
 
 . Create the `.netrc` file locally. See the link:https://everything.curl.dev/usingcurl/netrc.html[.netrc] docs for more details on the file format.
-. Create a key/value secret (see xref:/how-tos/configuring/creating-secrets.adoc[creating secrets for your builds]).
+. Create a key/value secret (see xref:/building/creating-secrets.adoc[creating secrets for your builds]).
   Set `.netrc` as the key. Upload the content of your `.netrc` file as the value.
 . In your `.tekton/` PipelineRun files, add the newly created secret to the `.spec.workspaces` section: