Automate documentation builds using GitHub Actions

For production use, deploy TechDocs by building documentation in CI/CD, publishing to external storage such as AWS S3, and configuring read-only mode. You can automate this workflow using GitHub Actions to generate and publish TechDocs when users update documentation files.

Before you begin

  • The TechDocs plugin is enabled and configured on your Red Hat Developer Hub instance.
  • Your organization has documentation files stored in a remote repository.
  • You have an mkdocs.yaml file located in the root directory of your repository.
  • You have the catalog.entity.create and catalog.location.create permissions to import documentation into TechDocs from a remote repository.
  • You have an AWS S3 bucket to store your TechDocs sites.
  • Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
  • An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.

Procedure

  1. Set up the GitHub Actions workflow.
    1. On GitHub, create a fork of the RHDH TechDocs Pipeline repository.
      Note

      The rhdh-techdocs-pipeline repository contains a generate-and-publish-techdocs.yaml workflow that automatically generates TechDocs from the docs folder and publishes them to an Amazon S3 bucket.

    2. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
    3. Add the Repository secrets required to connect the workflow to your AWS account, for example, TECHDOCS_S3_BUCKET_NAME, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION.
      Note

      The default mkdocs.yaml file in the rhdh-techdocs-pipeline workflow installs the techdocs-core and minify plugins.

    4. Optional: Customize the default structure or files of the rhdh-techdocs-pipeline repository to meet the needs of your organization.
    5. Optional: Add other mkdocs plugins that you want to use by adding the name of the plugins to the plugins section of the mkdocs.yaml file and to the steps.name: install mkdocs and mkdocs plugins section of the generate-and-publish-techdocs.yaml file.
  2. . In the navigation menu of the OpenShift Container Platform console, click ConfigMaps and select your RHDH app-config.yaml file.
  3. Update the app-config.yaml file to enable your Amazon S3 bucket to serve TechDocs to your RHDH instance. For example:
    techdocs:
      builder: external
      publisher:
        type: awsS3
        awsS3:
          bucketName: $AWS_S3_BUCKET_NAME}
          accountId: $AWS_ACCOUNT_ID}
          region: $AWS_REGION}
    
    aws:
      accounts:
        - accountId: $AWS_ACCOUNT_ID}
          accessKeyId: $AWS_ACCESS_KEY_ID}
          secretAccessKey: $AWS_SECRET_ACCESS_KEY}
    
    catalog:
         locations:
            - type: url
              target: https://github.com/<your_org>/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml
  4. Click Save.
  5. In the navigation menu of the OpenShift Container Platform console, click Topology and restart the pod.
    Note

    Changes to the docs folder or the mkdocs.yaml file trigger the rhdh-techdocs-pipeline workflow to run. After the rhdh-techdocs-pipeline workflow runs successfully, the generated TechDocs are uploaded to your Amazon S3 bucket.

Results

  • Go to your RHDH instance and click Docs to see the TechDocs served from your Amazon S3 bucket.