3.6. Generating TechDocs Pipelines with GitHub Actions

Procedure

1. Set up the GitHub Actions workflow.

   1. On GitHub, create a fork of the RHDH TechDocs Pipeline repository.

      참고

      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.

      참고

      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.

   참고

   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.

Verification

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