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:
-
Visit the rhdh/developer-hub-config repository in your GitLab instance.
-
Select Edit > Edit single file.
-
Uncomment the
--- TECHDOCS_PLUGIN ---section indynamic.pluginssection of the YAML, to enable the TechDocs and GitLab dynamic plugins.To uncomment multiple lines of code, highlight the lines and press
CMD + /(on macOS) orCTRL + /(on Linux/Windows).
-
Look for the YAML between the
--- TECHDOCS_CONFIG ---block and uncomment it. -
Find the
appConfig.catalog.providersconfiguration and uncomment the--- GITLAB_CATALOG_PROVIDER ---block as shown below.
-
Commit your changes with the message
feat: add gitlab autodiscovery. -
Click the Refresh button on the
backstageApplication in OpenShift GitOps.
Verify GitLab Entity Discovery is Active
-
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.
-
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-refthat tells the TechDocs plugin where to find the source for documentation builds for the Component.
-
Visit your instance of Red Hat Developer Hub and view the Software Catalog. Make sure that the
Kinddropdown is set to Component. You should see the global-techdocs Component.
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: localThis particular configuration is instructing TechDocs to build (builder) and store documentation locally (publisher.type), in the running Red Hat Developer Hub 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 other storage solution. 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 if an alternative storage solution is used.
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. Repository owners and authors can build their TechDocs using the TechDocs CLI.