Open topic with navigation

TIBCO® Control Plane 1.2.0

# 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 `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.

Organization Permissions

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

Repository Permissions

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

Note: While creating a personal access token, you can configure which permissions to enable at repository level and organization level. You can change it later from your GitHub development settings.

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

   - 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 below steps and replace the `$[VARIABLES]` with your own value. Refer to Backstage Documentation.

   Note: The following structure is for reference only.

       organization:
         name: TIBCO Software

       # Add additional configurations needed for integrations below, for e.g. We have added Github integration here.
       # See https://backstage.io/docs/integrations/ for more info
       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}

       # Software templates related default configurations
       scaffolder:
         # See https://backstage.io/docs/features/software-templates/configuration for software template options
         defaultAuthor:
           name: M.C. Hammer # Defaults to `Scaffolder`
           email: hammer@donthurtem.com # Defaults to `scaffolder@backstage.io`
         defaultCommitMessage: "U can't touch this" # Defaults to 'Initial commit'

       # 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,
               ]

       # Enables loading of the user/groups information from GitHub into the Backstage catalog
       orgCatalog:
         providers:
           github:
             providerId: <CUSTOM-PROVIDER-ID>
             orgUrl: https://github.com/<YOUR-GITHUB-ORG-NAME>
             schedule: # optional
               # supports cron, ISO duration, "human duration" as used in code
               frequency: { minutes: 30 }
               # supports ISO duration, "human duration" as used in code
               timeout: { minutes: 15 }
               initialDelay: { seconds: 0 }

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

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO® Control Plane

Copyright © 2023-2024. Cloud Software Group, Inc. All Rights Reserved.