GitHub

TIBCO Developer Hub supports integration with GitHub, which can be used as a source to store all the catalog-related information, technical documentation, and more. It hosts software templates that can be used to create software projects from scratch. This means you can manage and store all the information in a single place and use it in your application.

TIBCO Developer Hub uses a GitHub Organization to store all of its catalogs, technical documentation, and software templates. See Backstage Documentation to learn more about GitHub integration.

Personal Access Token

A personal access token (PAT) enables authentication with GitHub APIs to access private repositories containing crucial data for building software catalog. It also helps in accessing data from GitHub, creating projects from software templates, and storing them in new repositories created as a result of template invocation. You can link both public and private repositories to your developer hub.

The personal access tokens (PAT) are of two types:

• Individual PAT - For accounts that an individual manages.

• Organizational PAT - For accounts managed by an organization. For example, you are an enterprise and have a developer hub that serves various software catalogs and templates. So, this information needs to reside in one location.

Adding Personal Access Token

The personal access token (PAT) is a part of the app-config associated with your application. Ensure the below structure is added in your custom config file while provisioning.

The above image shows the ${GITHUB_TOKEN} as an environment variable that gets replaced by an actual token value. The value gets replaced with the GITHUB_TOKEN variable that comes from the Kubernetes Secrets Object.

Permissions for GitHub Personal Access Token

In your GitHub account, go to Settings, and click Developer Settings. From the personal access token, select the fine-grained tokens. Here, you can select on whose behalf the token is being generated. Select your organization that you want to link with the TIBCO Developer Hub, and complete the further steps.

A fine-grained token helps to configure restricted access to your organization and its data. For example, you can configure read or write permissions to repositories, view administrative data, and manage members in a repository. These two types of permissions get assigned to a personal access token:

• Organization permissions

• Repository permissions

The following is the minimum set of permissions required to integrate the TIBCO Developer Hub with GitHub. This helps you use a complete range of TIBCO Developer Hub features.

Permission	Type	Usage
Administration	Read & Write	Admin access to an organization
Custom Organization Roles	Read & Write	Create, edit, delete, and list custom organization roles. View system organization roles.
Custom Repository Roles	Read & Write	Create, edit, delete, and list the custom repository roles.
Events	Read Only	View events triggered by an activity in an organization.
Members	Read & Write	Organization members and teams. Fetch or change members and teams in an organization.
Organization Codespaces	Read & Write	Manage Codespaces for an organization.
Variables	Read & Write	Manage Actions organization variables.

Permission	Type	Usage
Actions	Read & Write
Administration	Read & Write	Required for repository - creation, deletion, updation, settings, teams, and collaborators.
Codespaces	Read & Write	GitHub Codespaces is an instant, cloud-based development environment that uses a container to provide you with common languages, tools, and utilities for development.
Commit Statuses	Read & Write	To fetch and make commits to a repository.
Contents	Read & Write	Repository contents, commits, branches, downloads, releases, and merges.
Environments	Read & Write	Manage repository environments.
Metadata	Read & Write	Search repositories, list collaborators, and access repository metadata.
Pull Requests	Read & Write	Pull requests and related comments, assignees, labels, milestones, and merges.
Actions	Read & Write	Manage Actions repository variables.

The following image covers all the required permissions to run your TIBCO Developer Hub (with GitHub integration).

Integrating the TIBCO Developer Hub with GitHub

To integrate the TIBCO Developer Hub with GitHub for running templates and registering components, perform the following steps.

Procedure

1. Create a Kubernetes secret in your data plane where the TIBCO Developer Hub is installed. To create a Kubernetes secret, complete the following steps.

   • Create a YAML config file by including the below structure and replace the ${VARIABLES} with your own values.

     apiVersion: v1
     kind: Secret
     metadata:
       name: tibco-hub-secrets
     type: Opaque
     stringdata:
       # replace with your values
       GITHUB_TOKEN: $<your-token-name>

   • To create the Kubernetes Secret, run the following command replacing the <REPLACE-WITH-YOUR-DP-NAMESPACE> with a namespace of your data plane.

     

2. To create an application config file (YAML file) comprised of required configurations. Follow the Provisining or Update Configuration steps and replace the $[VARIABLES] with your own value. Refer to Backstage Documentation.

   Note: The following structure is for reference only.

integrations:
  github:
    - host: github.com
      # This is a Personal Access Token or PAT from GitHub. You can find out how to generate this token, and more information.
      # About setting up the GitHub integration here: https://backstage.io/docs/getting-started/configuration#setting-up-a-github-integration
      token: ${GITHUB_TOKEN}

Linking GitHub Organization to Developer Hub

After creating and adding a personal access token to your developer hub instance, you will need to link your GitHub organization to import all data into your developer hub instance. Use the below structure and replace the org name with your-github-org-name.

# Configure auto discovery of Catalog
catalog:
  providers:
    # https://backstage.io/docs/integrations/github/discovery#configuration
    github:
      <CUSTOM-PROVIDER-ID>:
        organization: <your-GITHUB-org-name>
        schedule: # optional; same options as in TaskScheduleDefinition
          # supports cron, ISO duration, "human duration" as used in code
          frequency: { minutes: 30 }
          # supports ISO duration, "human duration" as used in code
          timeout: { minutes: 3 }
          initialDelay: { minutes: 0 }
    rules:
      - allow:
          [
            Component,
            API,
            Location,
            Template,
            User,
            Group,
            Domain,
            System,
            Resource,
          ]
  rules:
    - allow:
        [
          Component,
          API,
          Location,
          Template,
          User,
          Group,
          Domain,
          System,
          Resource,
        ]

Overcoming Throttling Issue by Rate Limiting

GitHub rate limits API requests to 5,000 per hour (or more for Enterprise accounts). The default catalog backend refreshes data every 100 seconds, which issues an API request for each discovered location.

If you have more than ~140 catalog entities, you may get throttled by rate limiting. You might see an error on the UI saying 403 Forbidden. Rate limit exceeded.

The default catalog refresh interval can be updated by adding a config catalogRefreshDelayInSec. The default value for this config is set to 100 seconds. The lower limit is 100 seconds and the upper limit is 900 seconds. See Backstage Documentation to learn more.

Top