Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Custom Tekton Hub instance

Red Hat OpenShift Pipelines 1.10

Installing a custom instance of Tekton Hub

Red Hat OpenShift Documentation Team

Abstract

This document provides information about installing and deploying a custom instance of Tekton Hub.
Important

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.

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.

Note

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>
...
      Copy to Clipboard Toggle word wrap

      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.

      Note
      • 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
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap
    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/
    Copy to Clipboard Toggle word wrap

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.

    Note

    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
      Copy to Clipboard Toggle word wrap
      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"}]
      Copy to Clipboard Toggle word wrap

    • To refresh all catalogs, run the following command: 

      $ curl -X POST -H "Authorization: <jwt-token>" \
      1 
      
  <api-url>/catalog/refresh
      2
      Copy to Clipboard Toggle word wrap
      1
      The Tekton Hub token copied from UI
      2
      The API pod URL.
  4. Refresh the page in the browser.

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.

Note

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
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap
    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.
    Copy to Clipboard Toggle word wrap

  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 * * * *"
  ...
    Copy to Clipboard Toggle word wrap

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
...
    Copy to Clipboard Toggle word wrap
    1
    The usernames registered with the Git repository hosting service provider.
    Note

    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
    Copy to Clipboard Toggle word wrap
    1
    The JWT token.

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"
    ...
    Copy to Clipboard Toggle word wrap

    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.

Legal Notice
Copy link

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat