Merge pull request #4475 from backstage/orkohunter/docs-techdocs-github-actions-ci-example

docs/features/techdocs/configuring-ci-cd.md

@@ -27,11 +27,15 @@ REPOSITORY_URL='https://github.com/org/repo'
 git clone $REPOSITORY_URL
 cd repo
 
+# Install @techdocs/cli, mkdocs and mkdocs plugins
+npm install -g @techdocs/cli
+pip install mkdocs-techdocs-core==0.*
+
 # Generate
-npx @techdocs/cli generate
+techdocs-cli generate --no-docker
 
 # Publish
-npx @techdocs/cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
+techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
 ```
 
 That's it!
@@ -40,14 +44,16 @@ Take a look at
 [`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
 complete command reference, details, and options.
 
-## 1. Setup a workflow
+## Steps
+
+### 1. Setup a workflow
 
 The TechDocs workflow should trigger on CI when any changes are made in the
 repository containing the documentation files. You can be specific and configure
 the workflow to be triggered only when files inside the `docs/` directory or
 `mkdocs.yml` are changed.
 
-## 2. Prepare step
+### 2. Prepare step
 
 The first step on the CI is to clone your documentation source repository in a
 working directory. This is almost always the first step in most CI workflows.
@@ -62,7 +68,7 @@ step.
 
 Eventually we are trying to do a `git clone <https://path/to/docs-repository/>`.
 
-## 3. Generate step
+### 3. Generate step
 
 Install [`npx`](https://www.npmjs.com/package/npx) to use it for running
 `techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`.
@@ -78,7 +84,7 @@ npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./
 `PATH_TO_REPO` should be the location in the file path where the prepare step
 above clones the repository.
 
-## 4. Publish step
+### 4. Publish step
 
 Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the
 necessary authentication environment variables.
@@ -96,3 +102,68 @@ npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <buc
 
 The updated TechDocs site built in this workflow is now ready to be served by
 the TechDocs plugin in your Backstage app.
+
+## Example: GitHub Actions CI and AWS S3
+
+Here is an example workflow using GitHub Actions CI and AWS S3 storage. You can
+use any CI and any other
+[TechDocs supported cloud storage providers](README.md#platforms-supported).
+
+Add a `.github/workflows/techdocs.yml` file in your
+[Software Template(s)](../software-templates/index.md) like this -
+
+```yaml
+name: Publish TechDocs Site
+
+on:
+  push:
+    branches: [main]
+    # You can even set it to run only when TechDocs related files are updated.
+    # paths:
+    #   - "docs/**"
+    #   - "mkdocs.yml"
+
+jobs:
+  publish-techdocs-site:
+    runs-on: ubuntu-latest
+
+    # The following secrets are required in your CI environment for publishing files to AWS S3.
+    # e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.
+    env:
+      TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_REGION: ${{ secrets.AWS_REGION }}
+      ENTITY_NAMESPACE: 'default'
+      ENTITY_KIND: 'Component'
+      ENTITY_NAME: 'my-doc-entity'
+      # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
+      # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
+      # ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v2
+      - uses: actions/setup-python@v2
+
+      - name: Install techdocs-cli
+        run: sudo npm install -g @techdocs/cli
+
+      - name: Install mkdocs and mkdocs plugins
+        run: python -m pip install mkdocs-techdocs-core==0.*
+
+      - name: Generate docs site
+        run: techdocs-cli generate --no-docker --verbose
+
+      - name: Publish docs site
+        run:
+          techdocs-cli publish --publisher-type awsS3 --storage-name
+          $TECHDOCS_S3_BUCKET_NAME --entity
+          $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
+```
+
+When the new repository is scaffolded or new documentation updates are
+committed, the GitHub Action workflow will publish the TechDocs site, which can
+be viewed in your Backstage app.