Activity: Enabling GitLab Entity Discovery & TechDocs

Now that the import of User and Group entities, and authentication is enabled for those same users, let’s focus on importing more Entities from your Git repositories.

Enable GitLab Entity Discovery and TechDocs

Much like the Keycloak provider, you can use a GitLab provider to discover and import Entities from repositories in GitLab. This functionality is provided by the @backstage/plugin-catalog-backend-module-gitlab plugin. You can see that this is a supported dynamic plugin in the Red Hat Developer Hub documentation.

To install and configure this plugin:

  1. Visit the rhdh/developer-hub-config repository in your GitLab instance.

  2. Select Edit > Edit single file.

  3. Uncomment the --- TECHDOCS_PLUGIN --- section in dynamic.plugins section of the YAML, to enable the TechDocs and GitLab dynamic plugins. Highlight the YAML and process CMD + / or CTRL + / to uncomment the necessary lines shown.

    TechDocs and GitLab dynamic plugins

  4. Look for the YAML between the --- TECHDOCS_CONFIG --- block. Highlight the block, then press CMD + / or CTRL + / to uncomment it.

  5. Find the appConfig.catalog.providers configuration and uncomment the following block as shown below.
    Look for the --- GITLAB_CATALOG_PROVIDER --- block; highlight the block, then press CMD + / or CTRL + /.

    GitLab Catalog Provider

  6. Commit your changes with the message feat: add gitlab autodiscovery.

  7. Click the Refresh button on the backstage Application in OpenShift GitOps.

Verify GitLab Entity Discovery is Active

  1. After a few moments your new Red Hat Developer Hub configuration will finish rolling out. Check the logs for the new Red Hat Developer Hub Pod. You should see that a repository was discovered - that means the repository contains catalog-info.yaml file.

    GitLab Autodiscovery Logs in the OpenShift Console

  2. The repository in question is the global/global-techdocs. This repository contains a catalog-info.yaml that defines a Component, and an annotation backstage.io/techdocs-ref that tells the TechDocs plugin where to find the source for documentation builds for the Component.

    Global TechDocs catalog-info.yaml file

  3. Visit your instance of Red Hat Developer Hub and view the Software Catalog. Make sure that the Kind dropdown is set to Component. You should see the global-techdocs Component.

    The Global TechDocs Component in the Software Catalog

Viewing TechDocs

  1. Click the global-techdocs Component name in the Software Catalog, and select the Docs tab.

    Global TechDocs being rendered

  2. It should compile and render the TechDocs.

    Global TechDocs being rendered

  3. You might have noticed that the side-menu has a new Docs entry too. This appeared when you enabled the TechDocs plugin!

    Docs side-menu

TechDocs Generation and Storage Configuration

Recall the techdocs configuration from your values.yaml file in GitLab. It should resemble the following example:

techdocs:
  builder: 'local'
  publisher:
    type: 'local'
  generator:
    runIn: local

This particular configuration is instructing TechDocs to build (builder) and store documentation locally (publisher.type), in the container.

The generator: local option instructs TechDocs to build the documentation on-demand. This requires the underlying container to have the necessary dependencies installed - Red Hat Developer Hub has these dependencies in place.

It’s possible to offload the TechDocs build process to a CI/CD pipeline that uses the TechDocs CLI. In this scenario, the pipeline builds and publishes the TechDocs to S3 or another storage system. The platform engineer must configure a builder of type external and the publisher to read from the same storage system to load the desired TechDocs for a given Entity.

Using the external builder strategy reduces load on the Red Hat Developer Hub instance, but places the burden of building and publishing the TechDocs on authors.

Conclusion

Congratulations! You’ve learned the core concepts of Backstage and Red Hat Developer Hub. You also learned how to deploy and manage an instance of Red Hat Developer Hub using the official Helm Chart via OpenShift GitOps.