diff --git a/cicd/pipelines/using-pipelines-as-code.adoc b/cicd/pipelines/using-pipelines-as-code.adoc index a8aa13b697fa..759a6cb78a60 100644 --- a/cicd/pipelines/using-pipelines-as-code.adoc +++ b/cicd/pipelines/using-pipelines-as-code.adoc @@ -6,10 +6,10 @@ include::_attributes/common-attributes.adoc[] toc::[] -// :FeatureName: Pipelines as Code +// :FeatureName: Pipelines as Code [role="_abstract"] -With {pac}, cluster administrators and users with the required privileges can define pipeline templates as part of source code Git repositories. When triggered by a source code push or a pull request for the configured Git repository, the feature runs the pipeline and reports the status. +With {pac}, cluster administrators and users with the required privileges can define pipeline templates as part of source code Git repositories. When triggered by a source code push or a pull request for the configured Git repository, {pac} runs the pipeline and reports the status. [id="pac-key-features"] == Key features @@ -17,7 +17,7 @@ With {pac}, cluster administrators and users with the required privileges can de * Pull request status and control on the platform hosting the Git repository. * GitHub Checks API to set the status of a pipeline run, including rechecks. -* GitHub pull request and commit events. +* GitHub pull request and commit events. * Pull request actions in comments, such as `/retest`. * Git events filtering and a separate pipeline for each event. * Automatic task resolution in {pipelines-shortname}, including local tasks, Tekton Hub, and remote URLs. @@ -31,7 +31,7 @@ include::modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc[le include::modules/op-installing-pipelines-as-code-cli.adoc[leveloffset=+1] [id="using-pipelines-as-code-with-a-git-repository-hosting-service-provider"] -== Using {pac} with a Git repository hosting service provider +== Using {pac} with a Git repository hosting service provider [role="_abstract"] After installing {pac}, cluster administrators can configure a Git repository hosting service provider. Currently, the following services are supported: @@ -51,6 +51,8 @@ include::modules/op-using-pipelines-as-code-with-a-github-app.adoc[leveloffset=+ include::modules/op-creating-a-github-application-in-administrator-perspective.adoc[leveloffset=+2] +include::modules/op-scoping-github-token.adoc[leveloffset=+2] + include::modules/op-using-pipelines-as-code-with-github-webhook.adoc[leveloffset=+1] .Additional resources @@ -90,6 +92,8 @@ include::modules/op-using-repository-crd-with-pipelines-as-code.adoc[leveloffset include::modules/op-setting-concurrency-limits-in-repository-crd.adoc[leveloffset=+2] +include::modules/op-changing-source-branch-in-repository-crd.adoc[leveloffset=+2] + include::modules/op-custom-parameter-expansion.adoc[leveloffset=+2] include::modules/op-using-pipelines-as-code-resolver.adoc[leveloffset=+1] diff --git a/modules/op-changing-source-branch-in-repository-crd.adoc b/modules/op-changing-source-branch-in-repository-crd.adoc new file mode 100644 index 000000000000..3228af7ea84e --- /dev/null +++ b/modules/op-changing-source-branch-in-repository-crd.adoc @@ -0,0 +1,29 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-pipelines-as-code.adoc + +:_content-type: REFERENCE +[id="changing-source-branch-in-repository-crd_{context}"] += Changing the source branch for the pipeline definition + +[role="_abstract"] +By default, when processing a push event or a pull request event, {pac} fetches the pipeline definition from the branch that triggered the event. You can use the `pipelinerun_provenance` setting in the `Repository` custom resource definition (CRD) to fetch the definition from the default branch configured on the Git repository provider, such as `main`, `master`, or `trunk`. + +[source,yaml] +---- +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: my-repo + namespace: target-namespace +spec: +# ... + settings: + pipelinerun_provenance: "default_branch" +# ... +---- + +[NOTE] +==== +You can use this setting as a security precaution. With the default behaviour, {pac} uses the pipeline definition in the submitted pull request. With the `default-branch` setting, the pipeline definition must be merged into the default branch before it is run. This requirement ensures maximum possible verification of any changes during merge review. +==== diff --git a/modules/op-customizing-pipelines-as-code-configuration.adoc b/modules/op-customizing-pipelines-as-code-configuration.adoc index 4b7b4f4565a4..fc3186ca2a2b 100644 --- a/modules/op-customizing-pipelines-as-code-configuration.adoc +++ b/modules/op-customizing-pipelines-as-code-configuration.adoc @@ -4,10 +4,10 @@ :_content-type: REFERENCE [id="customizing-pipelines-as-code-configuration_{context}"] -= Customizing {pac} configuration += Customizing {pac} configuration [role="_abstract"] -To customize {pac}, cluster administrators can configure the following parameters using the `pipelines-as-code` config map in the `openshift-pipelines` namespace: +To customize {pac}, cluster administrators can configure the following parameters in the `TektonConfig` custom resource, in the `pipelinesAsCode.settings` spec: .Customizing {pac} configuration [options="header"] @@ -17,11 +17,7 @@ To customize {pac}, cluster administrators can configure the following parameter | `application-name` | The name of the application. For example, the name displayed in the GitHub Checks labels. | `"Pipelines as Code CI"` -| `max-keep-days` | The number of the days for which the executed pipeline runs are kept in the `openshift-pipelines` namespace. - -Note that this `ConfigMap` setting does not affect the cleanups of a user's pipeline runs, which are controlled by the annotations on the pipeline run definition in the user's GitHub repository. | NA - -| `secret-auto-create` | Indicates whether or not a secret should be automatically created using the token generated in the GitHub application. This secret can then be used with private repositories. | `enabled` +| `secret-auto-create` | Indicates whether or not a secret should be automatically created using the token generated in the GitHub application. This secret can then be used with private repositories. | `enabled` | `remote-tasks` | When enabled, allows remote tasks from pipeline run annotations. | `enabled` @@ -43,6 +39,15 @@ Note that this `ConfigMap` setting does not affect the cleanups of a user's pipe | `auto-configure-repo-namespace-template` | Configures a template to automatically generate the namespace for your new repository, if `auto-configure-new-github-repo` is enabled. | `{repo_name}-pipelines` -| `error-log-snippet` | Enables or disables the view of a log snippet for the failed tasks, with an error in a pipeline. You can disable this parameter in the case of data leakage from your pipeline. | `enabled` +| `error-log-snippet` | Enables or disables the view of a log snippet for the failed tasks, with an error in a pipeline. You can disable this parameter in the case of data leakage from your pipeline. | `true` + +| `error-detection-from-container-logs` | Enables or disables the inspection of container logs to detect error message and expose them as annotations on the pull request. This setting applies only if you are using the GitHub app. | `true` + +| `error-detection-max-number-of-lines` | The maximum number of lines inspected in the container logs to search for error messages. Set to `-1` to inspect an unlimited number of lines. | 50 -|=== \ No newline at end of file +| `secret-github-app-token-scoped` | If set to `true`, the GitHub access token that {pac} generates using the GitHub app is scoped only to the repository from which {pac} fetches the pipeline definition. If set to `false`, you can use both the `TektonConfig` custom resource and the `Repository` custom resource to scope the token to additional repositories. | `true` + +| `secret-github-app-scope-extra-repos` | Additional repositories for scoping the generated GitHub access token. | + + +|=== diff --git a/modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc b/modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc index 478c0d997f95..2ccc73eff7b5 100644 --- a/modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc +++ b/modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc @@ -9,25 +9,28 @@ [role="_abstract"] {pac} is installed in the `openshift-pipelines` namespace when you install the {pipelines-title} Operator. For more details, see _Installing {pipelines-shortname}_ in the _Additional resources_ section. -To disable the default installation of {pac} with the Operator, set the value of the `enable` parameter to `false` in the `TektonConfig` custom resource. +To disable the default installation of {pac} with the Operator, set the value of the `enable` parameter to `false` in the `TektonConfig` custom resource. [source,yaml] ---- -... - spec: - platforms: - openshift: - pipelinesAsCode: - enable: false - settings: - application-name: Pipelines as Code CI - auto-configure-new-github-repo: "false" - bitbucket-cloud-check-source-ip: "true" - hub-catalog-name: tekton - hub-url: https://api.hub.tekton.dev/v1 - remote-tasks: "true" - secret-auto-create: "true" -... +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: + platforms: + openshift: + pipelinesAsCode: + enable: false + settings: + application-name: Pipelines as Code CI + auto-configure-new-github-repo: "false" + bitbucket-cloud-check-source-ip: "true" + hub-catalog-name: tekton + hub-url: https://api.hub.tekton.dev/v1 + remote-tasks: "true" + secret-auto-create: "true" +# ... ---- Optionally, you can run the following command: @@ -41,24 +44,27 @@ To enable the default installation of {pac} with the {pipelines-title} Operator, [source,yaml] ---- -... - spec: - platforms: - openshift: - pipelinesAsCode: - enable: true - settings: - application-name: Pipelines as Code CI - auto-configure-new-github-repo: "false" - bitbucket-cloud-check-source-ip: "true" - hub-catalog-name: tekton - hub-url: https://api.hub.tekton.dev/v1 - remote-tasks: "true" - secret-auto-create: "true" -... +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: + platforms: + openshift: + pipelinesAsCode: + enable: true + settings: + application-name: Pipelines as Code CI + auto-configure-new-github-repo: "false" + bitbucket-cloud-check-source-ip: "true" + hub-catalog-name: tekton + hub-url: https://api.hub.tekton.dev/v1 + remote-tasks: "true" + secret-auto-create: "true" +# ... ---- -Optionally, you can run the following command: +Optionally, you can run the following command: [source,terminal] ---- diff --git a/modules/op-installing-pipelines-operator-in-web-console.adoc b/modules/op-installing-pipelines-operator-in-web-console.adoc index db16a1f8442c..e94e646dc4dd 100644 --- a/modules/op-installing-pipelines-operator-in-web-console.adoc +++ b/modules/op-installing-pipelines-operator-in-web-console.adoc @@ -17,12 +17,12 @@ If you have {pipelines-shortname} already installed on your cluster, the existin If you manually changed your existing installation, such as, changing the target namespace in the `config.operator.tekton.dev` CRD instance by making changes to the `resource name - cluster` field, then the upgrade path is not smooth. In such cases, the recommended workflow is to uninstall your installation and reinstall the {pipelines-title} Operator. ==== -The {pipelines-title} Operator now provides the option to choose the components that you want to install by specifying profiles as part of the `TektonConfig` CR. The `TektonConfig` CR is automatically installed when the Operator is installed. +The {pipelines-title} Operator now provides the option to choose the components that you want to install by specifying profiles as part of the `TektonConfig` custom resource (CR). The `TektonConfig` CR is automatically installed when the Operator is installed. The supported profiles are: * Lite: This installs only Tekton Pipelines. -* Basic: This installs Tekton Pipelines and Tekton Triggers. -* All: This is the default profile used when the `TektonConfig` CR is installed. This profile installs all of the Tekton components: Tekton Pipelines, Tekton Triggers, Tekton Addons (which include `ClusterTasks`, `ClusterTriggerBindings`, `ConsoleCLIDownload`, `ConsoleQuickStart` and `ConsoleYAMLSample` resources). +* Basic: This installs Tekton Pipelines, Tekton Triggers, and Tekton Chains. +* All: This is the default profile used when the `TektonConfig` CR is installed. This profile installs all of the Tekton components, including Tekton Pipelines, Tekton Triggers, Tekton Chains, {pac}, and Tekton Addons. Tekton Addons includes the `ClusterTasks`, `ClusterTriggerBindings`, `ConsoleCLIDownload`, `ConsoleQuickStart`, and `ConsoleYAMLSample` resources. [discrete] .Procedure @@ -47,7 +47,7 @@ The supported profiles are: [NOTE] ==== Starting with {product-title} 4.11, the `preview` and `stable` channels for installing and upgrading the {pipelines-title} Operator are not available. However, in {product-title} 4.10 and earlier versions, you can use the `preview` and `stable` channels for installing and upgrading the Operator. -==== +==== . Click *Install*. You will see the Operator listed on the *Installed Operators* page. + @@ -74,7 +74,7 @@ $ oc get tektonconfig config .Example output ---- NAME VERSION READY REASON -config 1.9.2 True +config 1.9.2 True ---- + If the *READY* condition is *True*, the Operator and its components have been installed successfully. @@ -89,12 +89,11 @@ $ oc get tektonpipeline,tektontrigger,tektonaddon,pac .Example output ---- NAME VERSION READY REASON -tektonpipeline.operator.tekton.dev/pipeline v0.41.1 True +tektonpipeline.operator.tekton.dev/pipeline v0.41.1 True NAME VERSION READY REASON -tektontrigger.operator.tekton.dev/trigger v0.22.2 True +tektontrigger.operator.tekton.dev/trigger v0.22.2 True NAME VERSION READY REASON -tektonaddon.operator.tekton.dev/addon 1.9.2 True +tektonaddon.operator.tekton.dev/addon 1.9.2 True NAME VERSION READY REASON -openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.15.5 True +openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.15.5 True ---- - diff --git a/modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc b/modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc index 8a7e709a0e43..97065728d00d 100644 --- a/modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc +++ b/modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc @@ -4,7 +4,7 @@ :_content-type: REFERENCE [id="monitoring-pipeline-run-status-using-pipelines-as-code_{context}"] -= Monitoring pipeline run status using {pac} += Monitoring pipeline run status using {pac} [role="_abstract"] Depending on the context and supported tools, you can monitor the status of a pipeline run in different ways. @@ -25,12 +25,10 @@ When {pac} detects an error in one of the tasks of a pipeline, a small snippet c [discrete] .Annotations for log error snippets -In the {pac} config map, if you set the `error-detection-from-container-logs` parameter to `true`, {pac} detects the errors from the container logs and adds them as annotations on the pull request where the error occurred. +In the `TektonConfig` custom resource, in the `pipelinesAsCode.settings` spec, you can set the `error-detection-from-container-logs` parameter to `true`. In this case, {pac} detects the errors from the container logs and adds them as annotations on the pull request where the error occurred. -[IMPORTANT] -==== -This feature is in Technology Preview. -==== +:FeatureName: Adding annotations for log error snippets +include::snippets/technology-preview.adoc[] Currently, {pac} supports only the simple cases where the error looks like `makefile` or `grep` output of the following format: [source,yaml] @@ -38,7 +36,7 @@ Currently, {pac} supports only the simple cases where the error looks like `make ::: ---- -You can customize the regular expression used to detect the errors with the `error-detection-simple-regexp` field. The regular expression uses named groups to give flexibility on how to specify the matching. The groups needed to match are filename, line, and error. You can view the {pac} config map for the default regular expression. +You can customize the regular expression used to detect the errors with the `error-detection-simple-regexp` parameter. The regular expression uses named groups to give flexibility on how to specify the matching. The groups needed to match are `filename`, `line`, and `error`. You can view the {pac} config map for the default regular expression. [NOTE] ==== @@ -51,7 +49,7 @@ For webhook, when the event is a pull request, the status is added as a comment [discrete] .Failures -If a namespace is matched to a `Repository` CRD, {pac} emits its failure log messages in the Kubernetes events inside the namespace. +If a namespace is matched to a `Repository` custom resource definition (CRD), {pac} emits its failure log messages in the Kubernetes events inside the namespace. [discrete] .Status associated with Repository CRD @@ -73,4 +71,3 @@ Using the `tkn pac describe` command, you can extract the status of the runs ass [discrete] .Notifications {pac} does not manage notifications. If you need to have notifications, use the `finally` feature of pipelines. - diff --git a/modules/op-running-pipeline-run-using-pipelines-as-code.adoc b/modules/op-running-pipeline-run-using-pipelines-as-code.adoc index e7c0a452e3df..41292c58f5fb 100644 --- a/modules/op-running-pipeline-run-using-pipelines-as-code.adoc +++ b/modules/op-running-pipeline-run-using-pipelines-as-code.adoc @@ -4,7 +4,7 @@ :_content-type: REFERENCE [id="running-pipeline-run-using-pipelines-as-code_{context}"] -= Running a pipeline run using {pac} += Running a pipeline run using {pac} [role="_abstract"] With default configuration, {pac} runs any pipeline run in the `.tekton/` directory of the default branch of repository, when specified events such as pull request or push occurs on the repository. For example, if a pipeline run on the default branch has the annotation `pipelinesascode.tekton.dev/on-event: "[pull_request]"`, it will run whenever a pull request event occurs. @@ -28,7 +28,7 @@ If the pull request author does not meet the requirements, another user who meet [discrete] .Pipeline run execution -A pipeline run always runs in the namespace of the `Repository` CRD associated with the repository that generated the event. +A pipeline run always runs in the namespace of the `Repository` custom resource definition (CRD) associated with the repository that generated the event. You can observe the execution of your pipeline runs using the `tkn pac` CLI tool. diff --git a/modules/op-scoping-github-token.adoc b/modules/op-scoping-github-token.adoc new file mode 100644 index 000000000000..99934f37f15b --- /dev/null +++ b/modules/op-scoping-github-token.adoc @@ -0,0 +1,110 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-pipelines-as-code.adoc + +:_content-type: PROCEDURE +[id="scoping-github-token_{context}"] += Scoping the GitHub token to additional repositories + +{pac} uses the GitHub app to generate a GitHub access token. {pac} uses this token to retrieve the pipeline payload from the repository and to enable the CI/CD processes to interact with GitHub repositories. + +By default, the access token is scoped only to the repository from which {pac} retrieves the pipeline definition. In some cases, you might want the token to have access to additional repositories. For example, there might be a CI repository where the `.tekton/pr.yaml` file and source payload are located, but the build process defined in `pr.yaml` fetches tasks from a separate private CD repository. + +You can extend the scope of the GitHub token in two ways: + +* _Global configuration_: You can extend the GitHub token to a list of repositories in different namespaces. You must have administrative permissions to set this configuration. +* _Repository level configuration_: You can extend the GitHub token to a list of repositories that exist in the same namespace as the original repository. You do not need administrative permissions to set this configuration. + +.Procedure + +. In the `TektonConfig` custom resource (CR), in the `pipelinesAsCode.settings` spec, set the `secret-github-app-token-scoped` parameter to `false`. This setting enables scoping the GitHub token to private and public repositories listed in the global and repository level configuration. + +. To set global configuration for scoping the GitHub token, in the `TektonConfig` CR, in the `pipelinesAsCode.settings` spec, specify the additional repositories in the `secret-github-app-scope-extra-repos` parameter, as in the following example: ++ +[source,yaml] +---- +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: + platforms: + openshift: + pipelinesAsCode: + enable: true + settings: + secret-github-app-token-scoped: false + secret-github-app-scope-extra-repos: "owner2/project2, owner3/project3" +---- ++ +. To set repository level configuration for scoping the GitHub token, specify the additional repositories in the `github_app_token_scope_repos` parameter of the `Repository` CR, as in the following example: ++ +[source,yaml] +---- +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: test + namespace: test-repo +spec: + url: "https://github.com/linda/project" + settings: + github_app_token_scope_repos: + - "owner/project" + - "owner1/project1" +---- ++ +In this example, the `Repository` custom resource is associated with the `linda/project` repository in the `test-repo` namespace. The scope of the generated GitHub token is extended to the `owner/project` and `owner1/project1` repositories, as well as the `linda/project` repository. These repositories must exist under the `test-repo` namespace. ++ +[NOTE] +==== +The additional repositories can be public or private, but must reside in the same namespace as the repository with which the `Repository` resource is associated. + +If any of the repositories do not exist in the namespace, the scoping of the GitHub token fails with an error message: + +[source,terminal] +---- +failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repo +---- +==== + +.Result + +The generated GitHub token enables access to the additional repositories that you configured in the global and repository level configuration, as well as the original repository where the {pac} payload files are located. + +If you provide both global configuration and repository level configuration, the token is scoped to all the repositories from both configurations, as in the following example. + +.`TektonConfig` custom resource +[source,yaml] +---- +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: + platforms: + openshift: + pipelinesAsCode: + enable: true + settings: + secret-github-app-token-scoped: false + secret-github-app-scope-extra-repos: "owner2/project2, owner3/project3" +---- + +.`Repository` custom resource +[source,yaml] +---- +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: test + namespace: test-repo +spec: + url: "https://github.com/linda/project" + settings: + github_app_token_scope_repos: + - "owner/project" + - "owner1/project1" +---- + +The GitHub token is scoped to the `owner/project`, `owner1/project1`, `owner2/project2`, `owner3/project3`, and `linda/project` respositories. diff --git a/modules/op-setting-concurrency-limits-in-repository-crd.adoc b/modules/op-setting-concurrency-limits-in-repository-crd.adoc index 5b688666693d..23732d653973 100644 --- a/modules/op-setting-concurrency-limits-in-repository-crd.adoc +++ b/modules/op-setting-concurrency-limits-in-repository-crd.adoc @@ -4,20 +4,25 @@ :_content-type: REFERENCE [id="setting-concurrency-limits-in-repository-crd_{context}"] -= Setting concurrency limits in the `Repository` CRD += Setting concurrency limits [role="_abstract"] -You can use the `concurrency_limit` spec in the `Repository` CRD to define the maximum number of pipeline runs running simultaneously for a repository. +You can use the `concurrency_limit` spec in the `Repository` custom resource definition (CRD) to define the maximum number of pipeline runs running simultaneously for a repository. [source,yaml] ---- -... +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: my-repo + namespace: target-namespace spec: +# ... concurrency_limit: - ... +# ... + ---- If there are multiple pipeline runs matching an event, the pipeline runs that match the event start in an alphabetical order. For example, if you have three pipeline runs in the `.tekton` directory and you create a pull request with a `concurrency_limit` of `1` in the repository configuration, then all the pipeline runs are executed in an alphabetical order. At any given time, only one pipeline run is in the running state while the rest are queued. - diff --git a/modules/op-using-incoming-webhook-with-pipelines-as-code.adoc b/modules/op-using-incoming-webhook-with-pipelines-as-code.adoc index de7c8ec63618..224856f1ce8d 100644 --- a/modules/op-using-incoming-webhook-with-pipelines-as-code.adoc +++ b/modules/op-using-incoming-webhook-with-pipelines-as-code.adoc @@ -4,12 +4,12 @@ :_content-type: REFERENCE [id="using-incoming-webhook-with-pipelines-as-code_{context}"] -= Using incoming webhook with {pac} += Using incoming webhook with {pac} [role="_abstract"] Using an incoming webhook URL and a shared secret, you can start a pipeline run in a repository. -To use incoming webhooks, specify the following within the `spec` section of the `Repository` CRD: +To use incoming webhooks, specify the following within the `spec` section of the `Repository` custom resource definition (CRD): * The incoming webhook URL that {pac} matches. * The Git provider and the user token. Currently, {pac} supports `github`, `gitlab`, and `bitbucket-cloud`. @@ -55,7 +55,7 @@ stringData: secret: ---- -To trigger a pipeline run located in the `.tekton` directory of a Git repository, use the following command: +To trigger a pipeline run located in the `.tekton` directory of a Git repository, use the following command: [source,terminal] ---- @@ -64,5 +64,4 @@ $ curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secre {pac} matches the incoming URL and treats it as a `push` event. However, {pac} does not report status of the pipeline runs triggered by this command. -To get a report or a notification, add it directly with a `finally` task to your pipeline. Alternatively, you can inspect the `Repository` CRD with the `tkn pac` CLI tool. - +To get a report or a notification, add it directly with a `finally` task to your pipeline. Alternatively, you can inspect the `Repository` CRD with the `tkn pac` CLI tool. diff --git a/modules/op-using-pipelines-as-code-resolver.adoc b/modules/op-using-pipelines-as-code-resolver.adoc index b402e24bb40e..d67a3cb9e18d 100644 --- a/modules/op-using-pipelines-as-code-resolver.adoc +++ b/modules/op-using-pipelines-as-code-resolver.adoc @@ -4,14 +4,14 @@ :_content-type: REFERENCE [id="using-pipelines-as-code-resolver_{context}"] -= Using {pac} resolver += Using the {pac} resolver [role="_abstract"] The {pac} resolver ensures that a running pipeline run does not conflict with others. -To split your pipeline and pipeline run, store the files in the `.tekton/` directory or its subdirectories. +To split your pipeline and pipeline run, store the files in the `.tekton/` directory or its subdirectories. -If {pac} observes a pipeline run with a reference to a task or a pipeline in any YAML file located in the `.tekton/` directory, {pac} automatically resolves the referenced task to provide a single pipeline run with an embedded spec in a `PipelineRun` object. +If {pac} observes a pipeline run with a reference to a task or a pipeline in any YAML file located in the `.tekton/` directory, {pac} automatically resolves the referenced task to provide a single pipeline run with an embedded spec in a `PipelineRun` object. If {pac} cannot resolve the referenced tasks in the `Pipeline` or `PipelineSpec` definition, the run fails before applying any changes to the cluster. You can see the issue on your Git provider platform and inside the events of the target namespace where the `Repository` CR is located. @@ -26,4 +26,3 @@ The resolver uses such tasks literally, without any transformation. To test your pipeline run locally before sending it in a pull request, use the `tkn pac resolve` command. You can also reference remote pipelines and tasks. - diff --git a/modules/op-using-pipelines-as-code-with-bitbucket-cloud.adoc b/modules/op-using-pipelines-as-code-with-bitbucket-cloud.adoc index f57ce94e528c..1b3b4bf3056a 100644 --- a/modules/op-using-pipelines-as-code-with-bitbucket-cloud.adoc +++ b/modules/op-using-pipelines-as-code-with-bitbucket-cloud.adoc @@ -120,8 +120,8 @@ spec: * The `tkn pac create` and `tkn pac bootstrap` commands are not supported on Bitbucket Cloud. * Bitbucket Cloud does not support webhook secrets. To secure the payload and prevent hijacking of the CI, {pac} fetches the list of Bitbucket Cloud IP addresses and ensures that the webhook receptions come only from those IP addresses. -** To disable the default behavior, set the `bitbucket-cloud-check-source-ip key` to `false` in the {pac} config map for the `openshift-pipelines` namespace. -** To allow additional safe IP addresses or networks, add them as comma separated values to the `bitbucket-cloud-additional-source-ip` key in the {pac} config map for the `openshift-pipelines` namespace. +** To disable the default behavior, set the `bitbucket-cloud-check-source-ip` parameter to `false` in the `TektonConfig` custom resource, in the `pipelinesAsCode.settings` spec. +** To allow additional safe IP addresses or networks, add them as comma separated values to the `bitbucket-cloud-additional-source-ip` parameter in the `TektonConfig` custom resource, in the `pipelinesAsCode.settings` spec. ==== . Optional: For an existing `Repository` CR, add multiple Bitbucket Cloud Webhook secrets or provide a substitute for a deleted secret. @@ -196,4 +196,3 @@ spec: ---- $ oc -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}" ---- - diff --git a/modules/op-using-pipelines-as-code-with-bitbucket-server.adoc b/modules/op-using-pipelines-as-code-with-bitbucket-server.adoc index fbb97312995c..35e1f0c92452 100644 --- a/modules/op-using-pipelines-as-code-with-bitbucket-server.adoc +++ b/modules/op-using-pipelines-as-code-with-bitbucket-server.adoc @@ -4,17 +4,17 @@ :_content-type: PROCEDURE [id="using-pipelines-as-code-with-bitbucket-server_{context}"] -= Using {pac} with Bitbucket Server += Using {pac} with Bitbucket Server [role="_abstract"] -If your organization or project uses Bitbucket Server as the preferred platform, you can use {pac} for your repository with a webhook on Bitbucket Server. +If your organization or project uses Bitbucket Server as the preferred platform, you can use {pac} for your repository with a webhook on Bitbucket Server. [discrete] .Prerequisites * Ensure that {pac} is installed on the cluster. -* Generate a personal access token as the manager of the project on Bitbucket Server, and save a copy of it in an alternate location. +* Generate a personal access token as the manager of the project on Bitbucket Server, and save a copy of it in an alternate location. + [NOTE] ==== @@ -45,14 +45,14 @@ $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controlle [source,terminal] ---- $ openssl rand -hex 20 ----- +---- -.. Select the following events: +.. Select the following events: *** *Repository: Push* *** *Repository: Modified* *** *Pull Request: Opened* *** *Pull Request: Source branch updated* -*** *Pull Request: Comment added* +*** *Pull Request: Comment added* .. Click *Save*. @@ -70,23 +70,22 @@ $ oc -n target-namespace create secret generic bitbucket-server-webhook-config \ .Example: `Repository` CR [source,yaml] ---- ---- - apiVersion: "pipelinesascode.tekton.dev/v1alpha1" - kind: Repository - metadata: - name: my-repo - namespace: target-namespace - spec: - url: "https://bitbucket.com/workspace/repo" - git_provider: - url: "https://bitbucket.server.api.url/rest" <1> - user: "" <2> - secret: <3> - name: "bitbucket-server-webhook-config" - key: "provider.token" # Set this if you have a different key in your secret - webhook_secret: - name: "bitbucket-server-webhook-config" - key: "webhook.secret" # Set this if you have a different key for your secret +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: my-repo + namespace: target-namespace +spec: + url: "https://bitbucket.com/workspace/repo" + git_provider: + url: "https://bitbucket.server.api.url/rest" <1> + user: "" <2> + secret: <3> + name: "bitbucket-server-webhook-config" + key: "provider.token" # Set this if you have a different key in your secret + webhook_secret: + name: "bitbucket-server-webhook-config" + key: "webhook.secret" # Set this if you have a different key for your secret ---- <1> Ensure that you have the right Bitbucket Server API URL without the `/api/v1.0` suffix. Usually, the default install has a `/rest` suffix. <2> You can only reference a user by the `ACCOUNT_ID` in an owner file. @@ -94,5 +93,5 @@ $ oc -n target-namespace create secret generic bitbucket-server-webhook-config \ + [NOTE] ==== -The `tkn pac create` and `tkn pac bootstrap` commands are not supported on Bitbucket Server. -==== \ No newline at end of file +The `tkn pac create` and `tkn pac bootstrap` commands are not supported on Bitbucket Server. +==== diff --git a/modules/op-using-pipelines-as-code-with-github-webhook.adoc b/modules/op-using-pipelines-as-code-with-github-webhook.adoc index 21428652ab5d..3e3cd02a335c 100644 --- a/modules/op-using-pipelines-as-code-with-github-webhook.adoc +++ b/modules/op-using-pipelines-as-code-with-github-webhook.adoc @@ -4,7 +4,7 @@ :_content-type: PROCEDURE [id="using-pipelines-as-code-with-github-webhook_{context}"] -= Using {pac} with GitHub Webhook += Using {pac} with GitHub Webhook [role="_abstract"] Use {pac} with GitHub Webhook on your repository if you cannot create a GitHub App. However, using {pac} with GitHub Webhook does not give you access to the GitHub Check Runs API. The status of the tasks is added as comments on the pull request and is unavailable under the *Checks* tab. @@ -16,7 +16,7 @@ Use {pac} with GitHub Webhook on your repository if you cannot create a GitHub A [source,terminal] ---- $ git --amend -a --no-edit && git push --force-with-lease ----- +---- ==== [discrete] @@ -32,17 +32,17 @@ $ git --amend -a --no-edit && git push --force-with-lease [options="header"] |=== -| Name | Access +| Name | Access -| Administration | Read-only +| Administration | Read-only -| Metadata | Read-only +| Metadata | Read-only -| Content | Read-only +| Content | Read-only -| Commit statuses | Read and Write +| Commit statuses | Read and Write -| Pull request | Read and Write +| Pull request | Read and Write | Webhooks | Read and Write @@ -111,7 +111,7 @@ $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controlle [source,terminal] ---- $ openssl rand -hex 20 ----- +---- .... Click *Let me select individual events* and select these events: *Commit comments*, *Issue comments*, *Pull request*, and *Pushes*. @@ -198,12 +198,17 @@ $ tkn pac webhook update-token -n repo-pipelines + [source,yaml] ---- -... +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" +kind: Repository +metadata: + name: my-repo + namespace: target-namespace spec: +# ... git_provider: secret: name: "github-webhook-config" -... +# ... ---- ... Use the `oc patch` command to update the values of the `$NEW_TOKEN` in the `$target_namespace` namespace. diff --git a/modules/op-using-private-repositories-with-pipelines-as-code.adoc b/modules/op-using-private-repositories-with-pipelines-as-code.adoc index e43f21a65b2a..50a4a17ec19c 100644 --- a/modules/op-using-private-repositories-with-pipelines-as-code.adoc +++ b/modules/op-using-private-repositories-with-pipelines-as-code.adoc @@ -4,7 +4,7 @@ :_content-type: REFERENCE [id="using-private-repositories-with-pipelines-as-code_{context}"] -= Using private repositories with {pac} += Using private repositories with {pac} [role="_abstract"] {pac} supports private repositories by creating or updating a secret in the target namespace with the user token. The `git-clone` task from {tekton-hub} uses the user token to clone private repositories. @@ -52,5 +52,4 @@ tasks: ---- <1> The `git-clone` task picks up the `basic-auth` workspace and uses it to clone the private repository. -You can modify this configuration by setting the `secret-auto-create` flag to either a `false` or `true` value, as required in the {pac} config map. - +You can modify this configuration by setting the `secret-auto-create` parameter to either a `false` or `true` value, as required, in the `TektonConfig` custom resource, in the `pipelinesAsCode.settings` spec. diff --git a/modules/op-using-remote-task-annotations-with-pipelines-as-code.adoc b/modules/op-using-remote-task-annotations-with-pipelines-as-code.adoc index fa233669e89a..65578ccce69c 100644 --- a/modules/op-using-remote-task-annotations-with-pipelines-as-code.adoc +++ b/modules/op-using-remote-task-annotations-with-pipelines-as-code.adoc @@ -4,7 +4,7 @@ :_content-type: REFERENCE [id="using-remote-task-annotations-with-pipelines-as-code_{context}"] -= Using remote task annotations with {pac} += Using remote task annotations with {pac} [role="_abstract"] {pac} supports fetching remote tasks or pipelines by using annotations in a pipeline run. If you reference a remote task in a pipeline run, or a pipeline in a `PipelineRun` or a `PipelineSpec` object, the {pac} resolver automatically includes it. If there is any error while fetching the remote tasks or parsing them, {pac} stops processing the tasks. @@ -20,7 +20,7 @@ To include remote tasks, refer to the following examples of annotation: [source,yaml] ---- ... - pipelinesascode.tekton.dev/task: "git-clone" <1> + pipelinesascode.tekton.dev/task: "git-clone" <1> ... ---- <1> {pac} includes the latest version of the task from the {tekton-hub}. @@ -75,9 +75,9 @@ To include remote tasks, refer to the following examples of annotation: + [NOTE] ==== -* If you use GitHub and the remote task URL uses the same host as the `Repository` CRD, {pac} uses the GitHub token and fetches the URL using the GitHub API. +* If you use GitHub and the remote task URL uses the same host as the `Repository` custom resource definition (CRD), {pac} uses the GitHub token and fetches the URL using the GitHub API. + -For example, if you have a repository URL similar to `https://github.com//` and the remote HTTP URL references a GitHub blob similar to `https://github.com///blob///`, {pac} fetches the task definition files from that private repository with the GitHub App token. +For example, if you have a repository URL similar to `https://github.com//` and the remote HTTP URL references a GitHub blob similar to `https://github.com///blob///`, {pac} fetches the task definition files from that private repository with the GitHub App token. + When you work on a public GitHub repository, {pac} acts similarly for a GitHub raw URL such as `https://raw.githubusercontent.com/////`. @@ -94,5 +94,4 @@ When you work on a public GitHub repository, {pac} acts similarly for a GitHub r pipelinesascode.tekton.dev/task: "" <1> ... ---- -<1> Relative path to the local file containing the task definition. - +<1> Relative path to the local file containing the task definition. diff --git a/modules/op-using-repository-crd-with-pipelines-as-code.adoc b/modules/op-using-repository-crd-with-pipelines-as-code.adoc index 45acf0067ab8..421f907af938 100644 --- a/modules/op-using-repository-crd-with-pipelines-as-code.adoc +++ b/modules/op-using-repository-crd-with-pipelines-as-code.adoc @@ -4,14 +4,14 @@ :_content-type: REFERENCE [id="using-repository-crd-with-pipelines-as-code_{context}"] -= Using the `Repository` CRD with {pac} += Using the Repository custom resource definition (CRD) with {pac} [role="_abstract"] The `Repository` custom resource (CR) has the following primary functions: * Inform {pac} about processing an event from a URL. * Inform {pac} about the namespace for the pipeline runs. -* Reference an API secret, username, or an API URL necessary for Git provider platforms when using webhook methods. +* Reference an API secret, username, or an API URL necessary for Git provider platforms when using webhook methods. * Provide the last pipeline run status for a repository. You can use the `tkn pac` CLI or other alternative methods to create a `Repository` CR inside the target namespace. For example: @@ -38,4 +38,3 @@ Whenever there is an event coming from the URL such as `https://github.com/"` annotation. Such explicit targeting prevents a malicious actor from executing a pipeline run in a namespace to which they do not have access. ==== -