Chapter 3. Using Pipelines as Code with a Git repository hosting service provider
Chapter 3. Using Pipelines as Code with a Git repository hosting service provider After installing Pipelines as Code, cluster administrators can configure a Git repository hosting service provider. Currently, the following services are supported: GitHub App GitHub Webhook GitLab Bitbucket Data Center Bitbucket Cloud Note GitHub App is the recommended service for using with Pipelines as Code. 3.1. Using Pipelines as Code with a GitHub App GitHub Apps act as a point of integration with Red Hat OpenShift Pipelines and bring the advantage of Git-based workflows to OpenShift Pipelines. Cluster administrators can configure a single GitHub App for all cluster users. For GitHub Apps to work with Pipelines as Code, ensure that the webhook of the GitHub App points to the Pipelines as Code controller route (or ingress endpoint) that listens for GitHub events. There are three ways to set up a GitHub app for Pipelines as Code: Use the tkn command line utility. Use the Administrator perspective of the web console. Set up the app manually in GitHub and then create a secret for Pipelines as Code. By default, Pipelines as Code can communicate with one GitHub app. If you configured additional Pipelines as Code controllers to communicate with additional GitHub apps, configure each of the GitHub apps separately. You must set up GitHub apps for any additional controllers manually. 3.1.1. Configuring a GitHub App using the command line interface You can use the tkn command line utility to create a GitHub app and configure the Pipelines as Code controller for the GitHub app. Important If you created additional Pipelines as Code controllers to support additional GitHub apps, you can use this procedure only for the main controller. To create a GitHub app for an additional controller, use the manual procedure. Prerequisites You are logged on to the OpenShift Container Platform cluster as a cluster administrator. You installed the tkn command line utility with the tkn pac plugin. Procedure Enter the following command: USD tkn pac bootstrap github-app This command assumes that your account uses a standard github.com API endpoint. If you use a different GitHub API endpoint, for example, if you use GitHub Enterprise, use the --github-api-url option to specify the endpoint, as in the following example: Example command USD tkn pac bootstrap github-app --github-api-url https://github.com/enterprises/example-enterprise 3.1.2. Creating a GitHub App in administrator perspective As a cluster administrator, you can configure your GitHub App with the OpenShift Container Platform cluster to use Pipelines as Code. This configuration allows you to execute a set of tasks required for build deployment. Important If you created additional Pipelines as Code controllers to support additional GitHub apps, you can use this procedure only for the main controller. To create a GitHub app for an additional controller, use the manual procedure. Prerequisites You have installed the Red Hat OpenShift Pipelines pipelines-1.18 operator from the Operator Hub. Procedure In the administrator perspective, navigate to Pipelines using the navigation pane. Click Setup GitHub App on the Pipelines page. Enter your GitHub App name. For example, pipelines-ci-clustername-testui . Click Setup . Enter your Git password when prompted in the browser. Click Create GitHub App for <username> , where <username> is your GitHub user name. Verification After successful creation of the GitHub App, the OpenShift Container Platform web console opens and displays the details about the application. The details of the GitHub App are saved as a secret in the openShift-pipelines namespace. To view details such as name, link, and secret associated with the GitHub applications, navigate to Pipelines and click View GitHub App . 3.1.3. Configuring a GitHub App manually and creating a secret for Pipelines as Code You can use the GitHub user interface to create a GitHub app. Then you must create a secret that configures Pipelines as Code to connect to GitHub app. If you created additional Pipelines as Code controllers to support additional GitHub apps, you must use this procedure for the additional controllers. Procedure Sign in to your GitHub account. In the GitHub menu, select Settings Developer settings GitHub Apps , then click New GitHub App . Provide the following information in the GitHub App form: GitHub Application Name : OpenShift Pipelines Homepage URL : OpenShift Console URL Webhook URL : The Pipelines as Code route or ingress URL. You can find it by running the following command: USD echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') Alternatively, to configure the GitHub app for an additional Pipelines as Code controller, replace pipelines-as-code-controller with the name of the controller that you configured, as in the following example: Example command USD echo https://USD(oc get route -n openshift-pipelines pac_controller_2 -o jsonpath='{.spec.host}') Webhook secret : An arbitrary secret. You can generate a secret by running the following command: USD openssl rand -hex 20 Select the following items in the Repository permissions section: Checks : Read & Write Contents : Read & Write Issues : Read & Write Metadata : Read-only Pull request : Read & Write Select the following items in the Organization permissions section: Members : Read-only Plan : Read-only Subscribe to the following events: Check run Check suite Commit comment Issue comment Pull request Push Click Create GitHub App . On the Details page of the newly created GitHub App, note the App ID displayed at the top. In the Private keys section, click Generate Private key to automatically generate and download a private key for the GitHub app. Securely store the private key for future reference and usage. Install the created App on a repository that you want to use with Pipelines as Code. Configure Pipelines as Code to access the newly created GitHub App by entering the following command: USD oc -n openshift-pipelines create secret generic pipelines-as-code-secret \ 1 --from-literal github-private-key="USD(cat <PATH_PRIVATE_KEY>)" \ 2 --from-literal github-application-id="<APP_ID>" \ 3 --from-literal webhook.secret="<WEBHOOK_SECRET>" 4 1 If you created additional Pipelines as Code controllers to support additional GitHub apps and you are configuring the app for an additional controller, replace pipelines-as-code-secret with the name that you configured in the secretName parameter for the controller. 2 The path to the private key you downloaded while configuring the GitHub App. 3 The App ID of the GitHub App. 4 The webhook secret provided when you created the GitHub App. Note Pipelines as Code works automatically with GitHub Enterprise by detecting the header set from GitHub Enterprise and using it for the GitHub Enterprise API authorization URL. Additional resources Configuring additional Pipelines as Code controllers to support additional GitHub apps 3.1.4. Scoping the GitHub token to additional repositories Pipelines as Code uses the GitHub app to generate a GitHub access token. Pipelines as Code 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 Pipelines as Code 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: 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: 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: 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 Pipelines as Code 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 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 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. 3.2. Using Pipelines as Code with GitHub Webhook Use Pipelines as Code with GitHub Webhook on your repository if you cannot create a GitHub App. However, using Pipelines as Code 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. Note Pipelines as Code with GitHub Webhook does not support GitOps comments such as /retest and /ok-to-test . To restart the continuous integration (CI), create a new commit to the repository. For example, to create a new commit without any changes, you can use the following command: USD git --amend -a --no-edit && git push --force-with-lease <origin> <branchname> Prerequisites Ensure that Pipelines as Code is installed on the cluster. For authorization, create a personal access token on GitHub. To generate a secure and fine-grained token, restrict its scope to a specific repository and grant the following permissions: Table 3.1. Permissions for fine-grained tokens Name Access Administration Read-only Metadata Read-only Content Read-only Commit statuses Read and Write Pull request Read and Write Webhooks Read and Write To use classic tokens, set the scope as public_repo for public repositories and repo for private repositories. In addition, provide a short token expiration period and note the token in an alternate location. Note If you want to configure the webhook using the tkn pac CLI, add the admin:repo_hook scope. Procedure Configure the webhook and create a Repository custom resource (CR). To configure a webhook and create a Repository CR automatically using the tkn pac CLI tool, use the following command: USD tkn pac create repo Sample interactive output ? Enter the Git repository url (default: https://github.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository owner-repo has been created in repo-pipelines namespace [✓] Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: sJNwdmTifHTs): sJNwdmTifHTs i \ufe0fYou now need to create a GitHub personal access token, please checkout the docs at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token for the required scopes ? Please enter the GitHub access token: **************************************** [✓] Webhook has been created on repository owner/repo 🔑 Webhook Secret owner-repo has been created in the repo-pipelines namespace. 🔑 Repository CR owner-repo has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] We have detected your repository using the programming language Go. [✓] A basic template has been created in /home/Go/src/github.com/owner/repo/.tekton/pipelinerun.yaml, feel free to customize it. To configure a webhook and create a Repository CR manually , perform the following steps: On your OpenShift cluster, extract the public URL of the Pipelines as Code controller. USD echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') On your GitHub repository or organization, perform the following steps: Go to Settings -> Webhooks and click Add webhook . Set the Payload URL to the Pipelines as Code controller public URL. Select the content type as application/json . Add a webhook secret and note it in an alternate location. With openssl installed on your local machine, generate a random secret. USD openssl rand -hex 20 Click Let me select individual events and select these events: Commit comments , Issue comments , Pull request , and Pushes . Click Add webhook . On your OpenShift cluster, create a Secret object with the personal access token and webhook secret. USD oc -n target-namespace create secret generic github-webhook-config \ --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>" Create a Repository CR. Example: Repository CR apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://github.com/owner/repo" git_provider: secret: name: "github-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "github-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret Note Pipelines as Code assumes that the OpenShift Secret object and the Repository CR are in the same namespace. Optional: For an existing Repository CR, add multiple GitHub Webhook secrets or provide a substitute for a deleted secret. Add a webhook using the tkn pac CLI tool. Example: Additional webhook using the tkn pac CLI USD tkn pac webhook add -n repo-pipelines Sample interactive output [✓] Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH [✓] Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace. Update the webhook.secret key in the existing OpenShift Secret object. Optional: For an existing Repository CR, update the personal access token. Update the personal access token using the tkn pac CLI tool. Example: Updating personal access token using the tkn pac CLI USD tkn pac webhook update-token -n repo-pipelines Sample interactive output ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. Alternatively, update the personal access token by modifying the Repository CR. Find the name of the secret in the Repository CR. 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 USDNEW_TOKEN in the USDtarget_namespace namespace. USD oc -n USDtarget_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" Additional resources GitHub Webhook documentation on GitHub GitHub Check Runs documentation on GitHub Creating a personal access token on GitHub Classic tokens with pre-filled permissions 3.3. Using Pipelines as Code with GitLab If your organization or project uses GitLab as the preferred platform, you can use Pipelines as Code for your repository with a webhook on GitLab. Prerequisites Ensure that Pipelines as Code is installed on the cluster. For authorization, generate a personal access token as the manager of the project or organization on GitLab. Note If you want to configure the webhook using the tkn pac CLI, add the admin:repo_hook scope to the token. Using a token scoped for a specific project cannot provide API access to a merge request (MR) sent from a forked repository. In such cases, Pipelines as Code displays the result of a pipeline as a comment on the MR. Procedure Configure the webhook and create a Repository custom resource (CR). To configure a webhook and create a Repository CR automatically using the tkn pac CLI tool, use the following command: USD tkn pac create repo Sample interactive output ? Enter the Git repository url (default: https://gitlab.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository repositories-project has been created in repo-pipelines namespace [✓] Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo ? Please enter the project ID for the repository you want to be configured, project ID refers to an unique ID (e.g. 34405323) shown at the top of your GitLab project : 17103 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: lFjHIEcaGFlF): lFjHIEcaGFlF i \ufe0fYou now need to create a GitLab personal access token with `api` scope i \ufe0fGo to this URL to generate one https://gitlab.com/-/profile/personal_access_tokens, see https://is.gd/rOEo9B for documentation ? Please enter the GitLab access token: ************************** ? Please enter your GitLab API URL:: https://gitlab.com [✓] Webhook has been created on your repository 🔑 Webhook Secret repositories-project has been created in the repo-pipelines namespace. 🔑 Repository CR repositories-project has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] A basic template has been created in /home/Go/src/gitlab.com/repositories/project/.tekton/pipelinerun.yaml, feel free to customize it. To configure a webhook and create a Repository CR manually , perform the following steps: On your OpenShift cluster, extract the public URL of the Pipelines as Code controller. USD echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') On your GitLab project, perform the following steps: Use the left sidebar to go to Settings -> Webhooks . Set the URL to the Pipelines as Code controller public URL. Add a webhook secret and note it in an alternate location. With openssl installed on your local machine, generate a random secret. USD openssl rand -hex 20 Click Let me select individual events and select these events: Commit comments , Issue comments , Pull request , and Pushes . Click Save changes . On your OpenShift cluster, create a Secret object with the personal access token and webhook secret. USD oc -n target-namespace create secret generic gitlab-webhook-config \ --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>" Create a Repository CR. Example: Repository CR apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://gitlab.com/owner/repo" # The repository URL git_provider: #url: "https://gitlab.example.com/" 1 secret: name: "gitlab-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "gitlab-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret 1 If you are using a private instance of GitLab and not GitLab.com, uncomment this field and set it to the URL of your GitLab API. The GitLab API is the same host as the repository. For example, if the repository is https://gitlab.example.com/owner/repo , the API URL is https://gitlab.example.com/ . Note Pipelines as Code assumes that the OpenShift Secret object and the Repository CR are in the same namespace. Optional: For an existing Repository CR, add multiple GitLab Webhook secrets or provide a substitute for a deleted secret. Add a webhook using the tkn pac CLI tool. Example: Adding additional webhook using the tkn pac CLI USD tkn pac webhook add -n repo-pipelines Sample interactive output [✓] Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH [✓] Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace. Update the webhook.secret key in the existing OpenShift Secret object. Optional: For an existing Repository CR, update the personal access token. Update the personal access token using the tkn pac CLI tool. Example: Updating personal access token using the tkn pac CLI USD tkn pac webhook update-token -n repo-pipelines Sample interactive output ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. Alternatively, update the personal access token by modifying the Repository CR. Find the name of the secret in the Repository CR. ... spec: git_provider: secret: name: "gitlab-webhook-config" ... Use the oc patch command to update the values of the USDNEW_TOKEN in the USDtarget_namespace namespace. USD oc -n USDtarget_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" Additional resources GitLab Webhook documentation on GitLab 3.4. Using Pipelines as Code with Bitbucket Cloud If your organization or project uses Bitbucket Cloud as the preferred platform, you can use Pipelines as Code for your repository with a webhook on Bitbucket Cloud. Prerequisites Ensure that Pipelines as Code is installed on the cluster. Create an app password on Bitbucket Cloud. Check the following boxes to add appropriate permissions to the token: Account: Email , Read Workspace membership: Read , Write Projects: Read , Write Issues: Read , Write Pull requests: Read , Write Note If you want to configure the webhook using the tkn pac CLI, add the Webhooks : Read and Write permission to the token. Once generated, save a copy of the password or token in an alternate location. Procedure Configure the webhook and create a Repository CR. To configure a webhook and create a Repository CR automatically using the tkn pac CLI tool, use the following command: USD tkn pac create repo Sample interactive output ? Enter the Git repository url (default: https://bitbucket.org/workspace/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository workspace-repo has been created in repo-pipelines namespace [✓] Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> i \ufe0fYou now need to create a Bitbucket Cloud app password, please checkout the docs at https://is.gd/fqMHiJ for the required permissions ? Please enter the Bitbucket Cloud app password: ************************************ 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes [✓] Webhook has been created on repository workspace/repo 🔑 Webhook Secret workspace-repo has been created in the repo-pipelines namespace. 🔑 Repository CR workspace-repo has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] A basic template has been created in /home/Go/src/bitbucket/repo/.tekton/pipelinerun.yaml, feel free to customize it. To configure a webhook and create a Repository CR manually , perform the following steps: On your OpenShift cluster, extract the public URL of the Pipelines as Code controller. USD echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') On Bitbucket Cloud, perform the following steps: Use the left navigation pane of your Bitbucket Cloud repository to go to Repository settings -> Webhooks and click Add webhook . Set a Title . For example, "Pipelines as Code". Set the URL to the Pipelines as Code controller public URL. Select these events: Repository: Push , Pull Request: Created , Pull Request: Updated , and Pull Request: Comment created . Click Save . On your OpenShift cluster, create a Secret object with the app password in the target namespace. USD oc -n target-namespace create secret generic bitbucket-cloud-token \ --from-literal provider.token="<BITBUCKET_APP_PASSWORD>" Create a Repository CR. Example: Repository CR apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://bitbucket.com/workspace/repo" branch: "main" git_provider: user: "<BITBUCKET_USERNAME>" 1 secret: name: "bitbucket-cloud-token" 2 key: "provider.token" # Set this if you have a different key in your secret 1 You can only reference a user by the ACCOUNT_ID in an owner file. 2 Pipelines as Code assumes that the secret referred in the git_provider.secret spec and the Repository CR is in the same namespace. Note 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, Pipelines as Code 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 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. Add a webhook using the tkn pac CLI tool. Example: Adding additional webhook using the tkn pac CLI USD tkn pac webhook add -n repo-pipelines Sample interactive output [✓] Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes [✓] Webhook has been created on repository workspace/repo 🔑 Secret workspace-repo has been updated with webhook secret in the repo-pipelines namespace. Note Use the [-n <namespace>] option with the tkn pac webhook add command only when the Repository CR exists in a namespace other than the default namespace. Update the webhook.secret key in the existing OpenShift Secret object. Optional: For an existing Repository CR, update the personal access token. Update the personal access token using the tkn pac CLI tool. Example: Updating personal access token using the tkn pac CLI USD tkn pac webhook update-token -n repo-pipelines Sample interactive output ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. Note Use the [-n <namespace>] option with the tkn pac webhook update-token command only when the Repository CR exists in a namespace other than the default namespace. Alternatively, update the personal access token by modifying the Repository CR. Find the name of the secret in the Repository CR. ... spec: git_provider: user: "<BITBUCKET_USERNAME>" secret: name: "bitbucket-cloud-token" key: "provider.token" ... Use the oc patch command to update the values of the USDpassword in the USDtarget_namespace namespace. USD oc -n USDtarget_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" Additional resources Creating app password on Bitbucket Cloud (Atlassian documentation) Introducing Altassian Account ID and Nicknames in the Atlassian documentation 3.5. Using Pipelines as Code with Bitbucket Data Center If your organization or project uses Bitbucket Data Center as the preferred platform, you can use Pipelines as Code for your repository with a webhook on Bitbucket Data Center. Prerequisites Ensure that Pipelines as Code is installed on the cluster. Generate a personal access token as the manager of the project on Bitbucket Data Center, and save a copy of it in an alternate location. Note The token must have the PROJECT_ADMIN and REPOSITORY_ADMIN permissions. The token must have access to forked repositories in pull requests. Procedure On your OpenShift cluster, extract the public URL of the Pipelines as Code controller. USD echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') On Bitbucket Data Center, perform the following steps: Use the left navigation pane of your Bitbucket Data Center repository to go to Repository settings -> Webhooks and click Add webhook . Set a Title . For example, "Pipelines as Code". Set the URL to the Pipelines as Code controller public URL. Add a webhook secret and save a copy of it in an alternate location. If you have openssl installed on your local machine, generate a random secret using the following command: USD openssl rand -hex 20 Select the following events: Repository: Push Repository: Modified Pull Request: Opened Pull Request: Source branch updated Pull Request: Comment added Click Save . On your OpenShift cluster, create a Secret object with the app password in the target namespace. USD oc -n target-namespace create secret generic bitbucket-datacenter-webhook-config \ --from-literal provider.token="<PERSONAL_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>" Create a Repository CR. Example: Repository CR 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.datacenter.api.url/rest" 1 user: "<BITBUCKET_USERNAME>" 2 secret: 3 name: "bitbucket-datacenter-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "bitbucket-datacenter-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret 1 Ensure that you have the right Bitbucket Data Center 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. 3 Pipelines as Code assumes that the secret referred in the git_provider.secret spec and the Repository CR is in the same namespace. Note The tkn pac create and tkn pac bootstrap commands are not supported on Bitbucket Data Center. Additional resources Creating personal tokens on Bitbucket Data Center (Atlassian documentation) Managing webhooks on Bitbucket Data Center (Atlassian documentation) 3.6. Interfacing Pipelines as Code with custom certificates To configure Pipelines as Code with a Git repository that is accessible with a privately signed or custom certificate, you can expose the certificate to Pipelines as Code. Procedure If you have installed Pipelines as Code using the Red Hat OpenShift Pipelines Operator, you can add your custom certificate to the cluster using the Proxy object. The Operator exposes the certificate in all Red Hat OpenShift Pipelines components and workloads, including Pipelines as Code. Additional resources Enabling the cluster-wide proxy 3.7. Using private repositories with Pipelines as Code Pipelines as Code 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. Whenever Pipelines as Code creates a new pipeline run in the target namespace, it creates or updates a secret with the pac-gitauth-<REPOSITORY_OWNER>-<REPOSITORY_NAME>-<RANDOM_STRING> format. You must reference the secret with the basic-auth workspace in your pipeline run and pipeline definitions, which is then passed on to the git-clone task. ... workspace: - name: basic-auth secret: secretName: "{{ git_auth_secret }}" ... In the pipeline, you can reference the basic-auth workspace for the git-clone task to reuse: ... workspaces: - name basic-auth params: - name: repo_url - name: revision ... tasks: workspaces: - name: basic-auth workspace: basic-auth ... tasks: - name: git-clone-from-catalog taskRef: name: git-clone 1 params: - name: url value: USD(params.repo_url) - name: revision value: USD(params.revision) ... 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 parameter to either a false or true value, as required, in the TektonConfig custom resource, in the pipelinesAsCode.settings spec.
tkn pac bootstrap github-app tkn pac bootstrap github-app --github-api-url https://github.com/enterprises/example-enterprise echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') echo https://USD(oc get route -n openshift-pipelines pac_controller_2 -o jsonpath='{.spec.host}') openssl rand -hex 20 oc -n openshift-pipelines create secret generic pipelines-as-code-secret \ 1 --from-literal github-private-key="USD(cat <PATH_PRIVATE_KEY>)" \ 2 --from-literal github-application-id="<APP_ID>" \ 3 --from-literal webhook.secret="<WEBHOOK_SECRET>" 4 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" 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" failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repo 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" 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" git --amend -a --no-edit && git push --force-with-lease <origin> <branchname> tkn pac create repo ? Enter the Git repository url (default: https://github.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository owner-repo has been created in repo-pipelines namespace [✓] Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: sJNwdmTifHTs): sJNwdmTifHTs i \ufe0fYou now need to create a GitHub personal access token, please checkout the docs at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token for the required scopes ? Please enter the GitHub access token: **************************************** [✓] Webhook has been created on repository owner/repo 🔑 Webhook Secret owner-repo has been created in the repo-pipelines namespace. 🔑 Repository CR owner-repo has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] We have detected your repository using the programming language Go. [✓] A basic template has been created in /home/Go/src/github.com/owner/repo/.tekton/pipelinerun.yaml, feel free to customize it. echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') openssl rand -hex 20 oc -n target-namespace create secret generic github-webhook-config --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" --from-literal webhook.secret="<WEBHOOK_SECRET>" apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://github.com/owner/repo" git_provider: secret: name: "github-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "github-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret tkn pac webhook add -n repo-pipelines [✓] Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH [✓] Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace. tkn pac webhook update-token -n repo-pipelines ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: git_provider: secret: name: "github-webhook-config" oc -n USDtarget_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" tkn pac create repo ? Enter the Git repository url (default: https://gitlab.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository repositories-project has been created in repo-pipelines namespace [✓] Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo ? Please enter the project ID for the repository you want to be configured, project ID refers to an unique ID (e.g. 34405323) shown at the top of your GitLab project : 17103 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: lFjHIEcaGFlF): lFjHIEcaGFlF i \ufe0fYou now need to create a GitLab personal access token with `api` scope i \ufe0fGo to this URL to generate one https://gitlab.com/-/profile/personal_access_tokens, see https://is.gd/rOEo9B for documentation ? Please enter the GitLab access token: ************************** ? Please enter your GitLab API URL:: https://gitlab.com [✓] Webhook has been created on your repository 🔑 Webhook Secret repositories-project has been created in the repo-pipelines namespace. 🔑 Repository CR repositories-project has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] A basic template has been created in /home/Go/src/gitlab.com/repositories/project/.tekton/pipelinerun.yaml, feel free to customize it. echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') openssl rand -hex 20 oc -n target-namespace create secret generic gitlab-webhook-config --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" --from-literal webhook.secret="<WEBHOOK_SECRET>" apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://gitlab.com/owner/repo" # The repository URL git_provider: #url: "https://gitlab.example.com/" 1 secret: name: "gitlab-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "gitlab-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret tkn pac webhook add -n repo-pipelines [✓] Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH [✓] Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace. tkn pac webhook update-token -n repo-pipelines ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. spec: git_provider: secret: name: "gitlab-webhook-config" oc -n USDtarget_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" tkn pac create repo ? Enter the Git repository url (default: https://bitbucket.org/workspace/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes [✓] Repository workspace-repo has been created in repo-pipelines namespace [✓] Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> i \ufe0fYou now need to create a Bitbucket Cloud app password, please checkout the docs at https://is.gd/fqMHiJ for the required permissions ? Please enter the Bitbucket Cloud app password: ************************************ 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes [✓] Webhook has been created on repository workspace/repo 🔑 Webhook Secret workspace-repo has been created in the repo-pipelines namespace. 🔑 Repository CR workspace-repo has been updated with webhook secret in the repo-pipelines namespace i Directory .tekton has been created. [✓] A basic template has been created in /home/Go/src/bitbucket/repo/.tekton/pipelinerun.yaml, feel free to customize it. echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') oc -n target-namespace create secret generic bitbucket-cloud-token --from-literal provider.token="<BITBUCKET_APP_PASSWORD>" apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://bitbucket.com/workspace/repo" branch: "main" git_provider: user: "<BITBUCKET_USERNAME>" 1 secret: name: "bitbucket-cloud-token" 2 key: "provider.token" # Set this if you have a different key in your secret tkn pac webhook add -n repo-pipelines [✓] Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes [✓] Webhook has been created on repository workspace/repo 🔑 Secret workspace-repo has been updated with webhook secret in the repo-pipelines namespace. tkn pac webhook update-token -n repo-pipelines ? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace. spec: git_provider: user: "<BITBUCKET_USERNAME>" secret: name: "bitbucket-cloud-token" key: "provider.token" oc -n USDtarget_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"USD(echo -n USDNEW_TOKEN|base64 -w0)\"}}" echo https://USD(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}') openssl rand -hex 20 oc -n target-namespace create secret generic bitbucket-datacenter-webhook-config --from-literal provider.token="<PERSONAL_TOKEN>" --from-literal webhook.secret="<WEBHOOK_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.datacenter.api.url/rest" 1 user: "<BITBUCKET_USERNAME>" 2 secret: 3 name: "bitbucket-datacenter-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "bitbucket-datacenter-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret workspace: - name: basic-auth secret: secretName: "{{ git_auth_secret }}" workspaces: - name basic-auth params: - name: repo_url - name: revision tasks: workspaces: - name: basic-auth workspace: basic-auth tasks: - name: git-clone-from-catalog taskRef: name: git-clone 1 params: - name: url value: USD(params.repo_url) - name: revision value: USD(params.revision)