Pipelines as Code

Procedure

1. In the TektonConfig custom resource, add the additionalPACControllers section to the platforms.openshift.pipelinesAsCode spec, as in the following example:

   Example additionalPACControllers section

   apiVersion: operator.tekton.dev/v1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     platforms:
       openshift:
         pipelinesAsCode:
           additionalPACControllers:
             pac_controller_2:  1
               enable: true    2
               secretName: pac_secret_2  3
               settings: #  4
   # ...

   1

   The name of the controller. This name must be unique and not exceed 25 characters in length.

   2

   This parameter is optional. Set this parameter to true to enable the additional controller or to false to disable the additional controller. The default vaule is true.

   3

   Set this parameter to the name of a secret that you must create for the GitHub app.

   4

   This section is optional. In this section, you can set any Pipelines as Code settings for this controller if the settings must be different from the main Pipelines as Code controller.

2. Optional: If you want to use more than two GitHub apps, create additional sections under the pipelinesAsCode.additionalPACControllers spec to configure a Pipelines as Code controller for every GitHub instance. Use a unique name for every controller.

Procedure

1. 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:

     $ 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
     ℹ ️You 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
     ℹ 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:

     1. On your OpenShift cluster, extract the public URL of the Pipelines as Code controller.

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')

     2. On your GitHub repository or organization, perform the following steps:

        1. Go to Settings –> Webhooks and click Add webhook.
        2. Set the Payload URL to the Pipelines as Code controller public URL.
        3. Select the content type as application/json.

        4. Add a webhook secret and note it in an alternate location. With openssl installed on your local machine, generate a random secret.

           $ openssl rand -hex 20

        5. Click Let me select individual events and select these events: Commit comments, Issue comments, Pull request, and Pushes.
        6. Click Add webhook.

     3. On your OpenShift cluster, create a Secret object with the personal access token and webhook secret.

        $ oc -n target-namespace create secret generic github-webhook-config \
          --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" \
          --from-literal webhook.secret="<WEBHOOK_SECRET>"

     4. 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.

2. Optional: For an existing Repository CR, add multiple GitHub Webhook secrets or provide a substitute for a deleted secret.

   1. Add a webhook using the tkn pac CLI tool.

      Example: Additional webhook using the tkn pac CLI

      $ 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.

   2. Update the webhook.secret key in the existing OpenShift Secret object.

3. 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

     $ 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.

     1. 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"
        # ...

     2. Use the oc patch command to update the values of the $NEW_TOKEN in the $target_namespace namespace.

        $ oc -n $target_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"

Procedure

1. 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:

     $ 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
     ℹ ️You now need to create a GitLab personal access token with `api` scope
     ℹ ️Go 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
     ℹ 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:

     1. On your OpenShift cluster, extract the public URL of the Pipelines as Code controller.

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')

     2. On your GitLab project, perform the following steps:

        1. Use the left sidebar to go to Settings –> Webhooks.
        2. Set the URL to the Pipelines as Code controller public URL.

        3. Add a webhook secret and note it in an alternate location. With openssl installed on your local machine, generate a random secret.

           $ openssl rand -hex 20

        4. Click Let me select individual events and select these events: Commit comments, Issue comments, Pull request, and Pushes.
        5. Click Save changes.

     3. On your OpenShift cluster, create a Secret object with the personal access token and webhook secret.

        $ oc -n target-namespace create secret generic gitlab-webhook-config \
          --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" \
          --from-literal webhook.secret="<WEBHOOK_SECRET>"

     4. 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.

2. Optional: For an existing Repository CR, add multiple GitLab Webhook secrets or provide a substitute for a deleted secret.

   1. Add a webhook using the tkn pac CLI tool.

      Example: Adding additional webhook using the tkn pac CLI

      $ 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.

   2. Update the webhook.secret key in the existing OpenShift Secret object.

3. 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

     $ 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.

     1. Find the name of the secret in the Repository CR.

        ...
        spec:
          git_provider:
            secret:
              name: "gitlab-webhook-config"
        ...

     2. Use the oc patch command to update the values of the $NEW_TOKEN in the $target_namespace namespace.

        $ oc -n $target_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"

Procedure

1. 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:

     $ 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>
     ℹ ️You 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
     ℹ 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:

     1. On your OpenShift cluster, extract the public URL of the Pipelines as Code controller.

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')

     2. On Bitbucket Cloud, perform the following steps:

        1. Use the left navigation pane of your Bitbucket Cloud repository to go to Repository settings –> Webhooks and click Add webhook.
        2. Set a Title. For example, "Pipelines as Code".
        3. Set the URL to the Pipelines as Code controller public URL.
        4. Select these events: Repository: Push, Pull Request: Created, Pull Request: Updated, and Pull Request: Comment created.
        5. Click Save.

     3. On your OpenShift cluster, create a Secret object with the app password in the target namespace.

        $ oc -n target-namespace create secret generic bitbucket-cloud-token \
          --from-literal provider.token="<BITBUCKET_APP_PASSWORD>"

     4. 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.

2. Optional: For an existing Repository CR, add multiple Bitbucket Cloud Webhook secrets or provide a substitute for a deleted secret.

   1. Add a webhook using the tkn pac CLI tool.

      Example: Adding additional webhook using the tkn pac CLI

      $ 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.

   2. Update the webhook.secret key in the existing OpenShift Secret object.

3. 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

     $ 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.

     1. Find the name of the secret in the Repository CR.

        ...
        spec:
          git_provider:
            user: "<BITBUCKET_USERNAME>"
            secret:
              name: "bitbucket-cloud-token"
              key: "provider.token"
        ...

     2. Use the oc patch command to update the values of the $password in the $target_namespace namespace.

        $ oc -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"

Procedure

1. On your OpenShift cluster, extract the public URL of the Pipelines as Code controller.

   $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')

2. On Bitbucket Server, perform the following steps:

   1. Use the left navigation pane of your Bitbucket Data Center repository to go to Repository settings –> Webhooks and click Add webhook.
   2. Set a Title. For example, "Pipelines as Code".
   3. Set the URL to the Pipelines as Code controller public URL.

   4. 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:

      $ openssl rand -hex 20

   5. Select the following events:

      • Repository: Push
      • Repository: Modified
      • Pull Request: Opened
      • Pull Request: Source branch updated
      • Pull Request: Comment added
   6. Click Save.

3. On your OpenShift cluster, create a Secret object with the app password in the target namespace.

   $ oc -n target-namespace create secret generic bitbucket-server-webhook-config \
     --from-literal provider.token="<PERSONAL_TOKEN>" \
     --from-literal webhook.secret="<WEBHOOK_SECRET>"

4. 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.server.api.url/rest" 1
       user: "<BITBUCKET_USERNAME>" 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.

   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 Server.

Procedure

1. In the Administrator perspective of the web console, go to Administration → CustomResourceDefinitions.
2. Use the Search by name field to search for the tektonconfigs.operator.tekton.dev custom resource definition (CRD) and click TektonConfig to view the CRD Details page.
3. Click the Instances tab.
4. Click the config instance to view the TektonConfig CR details.
5. Click the YAML tab.

6. Edit the loglevel. fields under the .options.configMaps.pac-config-logging.data parameter based on your requirements.

   Example TektonConfig CR with the Pipelines as Code log level fields set to warn

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     platforms:
       openshift:
         pipelinesAsCode:
           options:
             configMaps:
               pac-config-logging:
                 data:
                   loglevel.pac-watcher: warn 1
                   loglevel.pipelines-as-code-webhook: warn 2
                   loglevel.pipelinesascode: warn 3
                   zap-logger-config: |
                     {
                       "level": "info",
                       "development": false,
                       "sampling": {
                         "initial": 100,
                         "thereafter": 100
                       },
                       "outputPaths": ["stdout"],
                       "errorOutputPaths": ["stderr"],
                       "encoding": "json",
                       "encoderConfig": {
                         "timeKey": "ts",
                         "levelKey": "level",
                         "nameKey": "logger",
                         "callerKey": "caller",
                         "messageKey": "msg",
                         "stacktraceKey": "stacktrace",
                         "lineEnding": "",
                         "levelEncoder": "",
                         "timeEncoder": "iso8601",
                         "durationEncoder": "",
                         "callerEncoder": ""
                       }
                     }

   1

   The log level for the pipelines-as-code-watcher component.

   2

   The log level for the pipelines-as-code-webhook component.

   3

   The log level for the pipelines-as-code-controller component.

7. Optional: Create a custom logging config map for the Pipelines as Code components by changing the .env.value for each component under the .options.deployments field. The example below shows the configuration with the custom config map called custom-pac-config-logging.

   Example TektonConfig CR with the Pipelines as Code custom logging config map

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     platforms:
       openshift:
         pipelinesAsCode:
           enable: true
           options:
             configMaps:
               custom-pac-config-logging:
                 data:
                   loglevel.pac-watcher: warn
                   loglevel.pipelines-as-code-webhook: warn
                   loglevel.pipelinesascode: warn
                   zap-logger-config: |
                     {
                       "level": "info",
                       "development": false,
                       "sampling": {
                         "initial": 100,
                         "thereafter": 100
                       },
                       "outputPaths": ["stdout"],
                       "errorOutputPaths": ["stderr"],
                       "encoding": "json",
                       "encoderConfig": {
                         "timeKey": "ts",
                         "levelKey": "level",
                         "nameKey": "logger",
                         "callerKey": "caller",
                         "messageKey": "msg",
                         "stacktraceKey": "stacktrace",
                         "lineEnding": "",
                         "levelEncoder": "",
                         "timeEncoder": "iso8601",
                         "durationEncoder": "",
                         "callerEncoder": ""
                       }
                     }
             deployments:
               pipelines-as-code-controller:
                 spec:
                   template:
                     spec:
                       containers:
                       - name: pac-controller
                         env:
                         - name: CONFIG_LOGGING_NAME
                           value: custom-pac-config-logging
               pipelines-as-code-watcher:
                 spec:
                   template:
                     spec:
                       containers:
                       - name: pac-watcher
                         env:
                         - name: CONFIG_LOGGING_NAME
                           value: custom-pac-config-logging
               pipelines-as-code-webhook:
                 spec:
                   template:
                     spec:
                       containers:
                       - name: pac-webhook
                         env:
                         - name: CONFIG_LOGGING_NAME
                           value: custom-pac-config-logging