OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Using Tekton Hub with OpenShift Pipelines

Tekton Hub is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Tekton Hub helps you discover, search, and share reusable tasks and pipelines for your CI/CD workflows. A public instance of Tekton Hub is available at hub.tekton.dev. Cluster administrators can also install and deploy a custom instance of Tekton Hub for enterprise use.

Installing and deploying Tekton Hub on a Red Hat OpenShift Pipelines cluster

Tekton Hub is an optional component; cluster administrators cannot install it using the TektonConfig custom resource (CR). To install and manage Tekton Hub, use the TektonHub CR.

If you are using Github Enterprise or Gitlab Enterprise, install and deploy Tekton Hub in the same network as the enterprise server. For example, if the enterprise server is running behind a VPN, deploy Tekton Hub on a cluster that is also behind the VPN.
Prerequisites

  • Ensure that the Red Hat OpenShift Pipelines Operator is installed in the default openshift-pipelines namespace on the cluster.

Procedure

  1. Create a fork of the Tekton Hub repository.

  2. Clone the forked repository.

  3. Update the config.yaml file to include at least one user with the following scopes:

    • A user with agent:create scope who can set up a cron job that refreshes the Tekton Hub database after an interval, if there are any changes in the catalog.

    • A user with the catalog:refresh scope who can refresh the catalog and all resources in the database of the Tekton Hub.

    • A user with the config:refresh scope who can get additional scopes.

      ...
scopes:
- name: agent:create
  users: <username_registered_with_the_Git_repository_hosting_service_provider>
- name: catalog:refresh
  users: <username_registered_with_the_Git_repository_hosting_service_provider>
- name: config:refresh
  users: <username_registered_with_the_Git_repository_hosting_service_provider>
...

      The supported service providers are GitHub, GitLab, and BitBucket.

  4. Create an OAuth application with your Git repository hosting provider, and note the Client ID and Client Secret.

    • For a GitHub OAuth application, set the Homepage URL and the Authorization callback URL as <auth-route>.

    • For a GitLab OAuth application, set the REDIRECT_URI as <auth-route>/auth/gitlab/callback.

    • For a BitBucket OAuth application, set the Callback URL as <auth-route>.

  5. Edit the following fields in the <tekton_hub_repository>/config/02-api/20-api-secret.yaml file for the Tekton Hub API secret:

    • GH_CLIENT_ID: The Client ID from the OAuth application created with the Git repository hosting service provider.

    • GH_CLIENT_SECRET: The Client Secret from the OAuth application created with the Git repository hosting service provider.

    • GHE_URL: GitHub Enterprise URL, if you are authenticating using GitHub Enterprise. Do not provide the URL to the catalog as a value for this field.

    • GL_CLIENT_ID: The Client ID from the GitLab OAuth application.

    • GL_CLIENT_SECRET: The Client Secret from the GitLab OAuth application.

    • GLE_URL: GitLab Enterprise URL, if you are authenticating using GitLab Enterprise. Do not provide the URL to the catalog as a value for this field.

    • BB_CLIENT_ID: The Client ID from the BitBucket OAuth application.

    • BB_CLIENT_SECRET: The Client Secret from the BitBucket OAuth application.

    • JWT_SIGNING_KEY: A long, random string used to sign the JSON Web Token (JWT) created for users.

    • ACCESS_JWT_EXPIRES_IN: Add the time limit after which the access token expires. For example, 1m, where m denotes minutes. The supported units of time are seconds (s), minutes (m), hours (h), days (d), and weeks (w).

    • REFRESH_JWT_EXPIRES_IN: Add the time limit after which the refresh token expires. For example, 1m, where m denotes minutes. The supported units of time are seconds (s), minutes (m), hours (h), days (d), and weeks (w). Ensure that the expiry time set for token refresh is greater than the expiry time set for token access.

    • AUTH_BASE_URL: Route URL for the OAuth application.

      • Use the fields related to Client ID and Client Secret for any one of the supported Git repository hosting service providers.

      • The account credentials registered with the Git repository hosting service provider enables the users with catalog: refresh scope to authenticate and load all catalog resources to the database.

  6. Commit and push the changes to your forked repository.

  7. Ensure that the TektonHub CR is similar to the following example:

    apiVersion: operator.tekton.dev/v1alpha1
kind: TektonHub
metadata:
  name: hub
spec:
  targetNamespace: openshift-pipelines (1)
  api:
    hubConfigUrl: https://raw.githubusercontent.com/tektoncd/hub/main/config.yaml (2)
    1 The namespace in which Tekton Hub must be installed; default is openshift-pipelines.
    2 Substitute with the URL of the config.yaml file of your forked repository.

  8. Install the Tekton Hub.

    $ oc apply -f TektonHub.yaml (1)
    1 The file name or path of the TektonConfig CR.

  9. Check the status of the installation.

    $ oc get tektonhub.operator.tekton.dev
NAME   VERSION   READY   REASON   APIURL                    UIURL
hub    v1.7.2    True             https://api.route.url/    https://ui.route.url/

Manually refreshing the catalog in Tekton Hub

When you install and deploy Tekton Hub on a Red Hat OpenShift Pipelines cluster, a Postgres database is also installed. Initially, the database is empty. To add the tasks and pipelines available in the catalog to the database, cluster administrators must refresh the catalog.

Prerequisites

  • Ensure that you are in the <tekton_hub_repository>/config/ directory.

Procedure

  1. In the Tekton Hub UI, click Login -→ Sign In With GitHub.

    GitHub is used as an example from the publicly available Tekton Hub UI. For custom installation on your cluster, all Git repository hosting service providers for which you have provided Client ID and Client Secret are listed.

  2. On the home page, click the user profile and copy the token.

  3. Call the Catalog Refresh API.

    • To refresh a catalog with a specific name, run the following command:

      $ curl -X POST -H "Authorization: <jwt-token>" \ (1)
  <api-url>/catalog/<catalog_name>/refresh (2)
      1 The Tekton Hub token copied from UI.
      2 The API pod URL and name of the catalog.

      Sample output:

      [{"id":1,"catalogName":"tekton","status":"queued"}]

    • To refresh all catalogs, run the following command:

      $ curl -X POST -H "Authorization: <jwt-token>" \ (1)
  <api-url>/catalog/refresh (2)
      1 The Tekton Hub token copied from UI
      2 The API pod URL.

  4. Refresh the page in the browser.

Optional: Setting a cron job for refreshing catalog in Tekton Hub

Cluster administrators can optionally set up a cron job to refresh the database after a fixed interval, so that changes in the catalog appear in the Tekton Hub web console.

If resources are added to the catalog or updated, refreshing the catalog displays these changes in the Tekton Hub UI. However, if a resource is deleted from the catalog, refreshing the catalog does not remove the resource from the database. The Tekton Hub UI continues displaying the deleted resource.
Prerequisites

  • Ensure that you are in the <project_root>/config/ directory, where <project_root> is the top level directory of the cloned Tekton Hub repository.

  • Ensure that you have a JSON web token (JWT) token with a scope of refreshing the catalog.

Procedure

  1. Create an agent-based JWT token for longer use.

    $ curl -X PUT --header "Content-Type: application/json" \
    -H "Authorization: <access-token>" \ (1)
    --data '{"name":"catalog-refresh-agent","scopes": ["catalog:refresh"]}' \
    <api-route>/system/user/agent
    1 The JWT token.

    The agent token with the necessary scopes are returned in the {"token":"<agent_jwt_token>"} format. Note the returned token and preserve it for the catalog refresh cron job.

  2. Edit the 05-catalog-refresh-cj/50-catalog-refresh-secret.yaml file to set the HUB_TOKEN parameter to the <agent_jwt_token> returned in the previous step.

    apiVersion: v1
kind: Secret
metadata:
  name: catalog-refresh
type: Opaque
stringData:
  HUB_TOKEN: <hub_token> (1)
    1 The <agent_jwt_token> returned in the previous step.

  3. Apply the modified YAML files.

    $ oc apply -f 05-catalog-refresh-cj/ -n openshift-pipelines.

  4. Optional: By default, the cron job is configured to run every 30 minutes. To change the interval, modify the value of the schedule parameter in the 05-catalog-refresh-cj/51-catalog-refresh-cronjob.yaml file.

    apiVersion: batch/v1
kind: CronJob
metadata:
  name: catalog-refresh
  labels:
    app: tekton-hub-api
spec:
  schedule: "*/30 * * * *"
  ...

Optional: Adding new users in Tekton Hub configuration

Procedure

  1. Depending on the intended scope, cluster administrators can add new users in the config.yaml file.

    ...
scopes:
  - name: agent:create
    users: [<username_1>, <username_2>] (1)
  - name: catalog:refresh
    users: [<username_3>, <username_4>]
  - name: config:refresh
    users: [<username_5>, <username_6>]

default:
  scopes:
    - rating:read
    - rating:write
...
    1 The usernames registered with the Git repository hosting service provider.

    When any user logs in for the first time, they will have only the default scope even if they are added in the config.yaml. To activate additional scopes, ensure the user has logged in at least once.

  2. Ensure that in the config.yaml file, you have the config-refresh scope.

  3. Refresh the configuration.

    $ curl -X POST -H "Authorization: <access-token>" \ (1)
    --header "Content-Type: application/json" \
    --data '{"force": true} \
    <api-route>/system/config/refresh
    1 The JWT token.

Opting out of Tekton Hub in the Developer perspective

Cluster administrators can opt out of displaying Tekton Hub resources, such as tasks and pipelines, in the Pipeline builder page of the Developer perspective of an Red Hat OpenShift Pipelines cluster.

Prerequisite

  • Ensure that the Red Hat OpenShift Pipelines Operator is installed on the cluster, and the oc command line tool is available.

Procedure

  • To opt of displaying Tekton Hub resources in the Developer perspective, set the value of the enable-devconsole-integration field in the TektonConfig custom resource (CR) to false.

    apiVersion: operator.tekton.dev/v1alpha1
  kind: TektonConfig
  metadata:
    name: config
  spec:
    targetNamespace: openshift-pipelines
    ...
    hub:
      params:
        - name: enable-devconsole-integration
          value: "false"
    ...

    By default, the TektonConfig CR does not include the enable-devconsole-integration field, and the Red Hat OpenShift Pipelines Operator assumes that the value is true.

Additional resources