|
| 1 | +// Module included in the following assemblies: |
| 2 | +// |
| 3 | +// * assemblies/assembly-using-techdocs.adoc |
| 4 | + |
| 5 | +:_mod-docs-content-type: PROCEDURE |
| 6 | +[id="proc-techdocs-pipeline-github-actions_{context}"] |
| 7 | += Generating TechDocs Pipelines with GitHub Actions |
| 8 | + |
| 9 | +{product} ({product-very-short}) includes a built-in TechDocs builder, however, the default setup is not intended for production use. Deploying TechDocs documentation in a production environment involves the following actions: |
| 10 | + |
| 11 | +* *Building the documentation in a CI/CD system* |
| 12 | +* *Publishing the generated documentation site to external object storage*, such as AWS S3, to ensure that the generated documentation persists between restarts of {product-very-short} and can handle larger documentation workloads. |
| 13 | +* *Configuring TechDocs in your {product-very-short} deployment to run in read-only mode* so that TechDocs reads the static generated documentation files from the cloud storage bucket without attempting to generate them at runtime. |
| 14 | +
|
| 15 | +You can implement a TechDocs pipeline using GitHub Actions to automatically generate and publish your TechDocs whenever a user in your organization makes a change to a documentation file stored in your GitHub respository. |
| 16 | + |
| 17 | +.Prerequisites |
| 18 | + |
| 19 | +* The TechDocs plugin is enabled and configured on your {product-very-short} instance. |
| 20 | +* Your organization has documentation files stored in a remote repository. |
| 21 | +* You have an mkdocs.yaml file located in the root directory of your repository. |
| 22 | +* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository. |
| 23 | +* You have an AWS S3 bucket created to store your TechDocs sites. |
| 24 | +* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access. |
| 25 | +* An IAM User has been created, the necessary policy attached, and an access key generated. |
| 26 | +
|
| 27 | +.Procedure |
| 28 | + |
| 29 | +. Set up the GitHub Actions workflow |
| 30 | +.. On GitHub, create a fork of the `rhdh-techdocs-pipeline` repository. |
| 31 | ++ |
| 32 | +[NOTE] |
| 33 | +==== |
| 34 | +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. |
| 35 | +==== |
| 36 | ++ |
| 37 | +.. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled. |
| 38 | +.. Add the *Repository secrets* required to connect the workflow to your AWS account. |
| 39 | ++ |
| 40 | +[NOTE] |
| 41 | +==== |
| 42 | +The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins. |
| 43 | +==== |
| 44 | +.. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization. |
| 45 | +.. 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. |
| 46 | +. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. |
| 47 | +.. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file. |
| 48 | +.. In the `techdocs` section of the `app-config.yaml` file, set `builder` to `external`. |
| 49 | +.. Set `publisher.type` to `awsS3`. |
| 50 | +.. In the `aws` section, set `accounts.accountId` to `$(AWS_ACCOUNT_ID)`, set `accounts.accessKeyId` to `$(AWS_ACCESS_KEY_ID)`, and set `accounts.secretAccessKey` to `$(AWS_SECRET_ACCESS_KEY)`. |
| 51 | +.. In the `catalog` section, set `locations.type` to `url` and set `locations.target` to the url to the `catalog-info.yaml` file in your `rhdh-techdocs-pipeline` repository. |
| 52 | +. Click *Save*. |
| 53 | +. In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod. |
| 54 | ++ |
| 55 | +[NOTE] |
| 56 | +==== |
| 57 | +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. |
| 58 | +==== |
| 59 | + |
| 60 | +.Verification |
| 61 | +. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket. |
0 commit comments