From d9de82ee6c24eb8e84f27bdd490dc456316743c3 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Sat, 9 Jan 2021 23:04:22 +0100
Subject: [PATCH] docs: How to build TechDocs sites on CI/CD workflows

---
 docs/features/techdocs/architecture.md      |  5 +-
 docs/features/techdocs/configuring-ci-cd.md | 87 +++++++++++++++++++++
 microsite/sidebars.json                     |  1 +
 3 files changed, 90 insertions(+), 3 deletions(-)
 create mode 100644 docs/features/techdocs/configuring-ci-cd.md

diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md
index 7c35fbc943..53149ae4f3 100644
--- a/docs/features/techdocs/architecture.md
+++ b/docs/features/techdocs/architecture.md
@@ -142,12 +142,11 @@ Status of all the features mentioned above.
 
 - Basic setup with techdocs-backend file server as storage.
 - Basic setup with cloud storage solution.
-
-**Work in progress 🚧**
-
 - `techdocs-cli` is able to generate docs in CI/CD environment.
 - `techdocs-cli` is able to publish docs site to any storage.
 
+**Work in progress 🚧**
+
 **Not implemented yet ❌**
 
 - `techdocs-backend` integration with Backstage access control management.
diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md
new file mode 100644
index 0000000000..ec25684a94
--- /dev/null
+++ b/docs/features/techdocs/configuring-ci-cd.md
@@ -0,0 +1,87 @@
+---
+id: configuring-ci-cd
+title: Configuring CI/CD to generate and publish TechDocs sites
+description:
+  Configuring CI/CD to generate and publish TechDocs sites to cloud storage
+---
+
+In the [Recommended deployment setup](./architecture.md#recommended-deployment),
+TechDocs reads the static generated documentation files from a cloud storage
+bucket (GCS, AWS S3, etc.). The documentation site is generated on the CI/CD
+workflow associated with the repository containing the documentation files. This
+document explains the steps needed to generate docs on CI and publish to a cloud
+storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli).
+
+The steps here target all kinds of CI providers (GitHub actions, Circle CI,
+Jenkins, etc.) Specific tools for individual providers will also be made
+available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.)
+
+A summary of the instructions below looks like this -
+
+```sh
+# Prepare
+REPOSITORY_URL='https://github.com/org/repo'
+git clone $REPOSITORY_URL
+
+# Generate
+npx techdocs-cli generate --source-dir ./repo --output-dir ./site
+
+# Publish
+npx techdocs-cli publish --directory ./site --publisher-type awsS3 --bucket-name <bucket> --entity <Namespace/Kind/Name>
+
+# That's it!
+```
+
+## 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 trigger
+the workflow only on changes to files inside the `docs/` directory or
+`mkdocs.yml`.
+
+## 2. Prepare step
+
+The first step on the CI is to clone the repository in a working directory. This
+is almost always the first step in most CI workflows.
+
+On GitHub actions, you can add a step
+
+[`- uses: actions@checkout@v2`](https://github.com/actions/checkout).
+
+On CircleCI, you can add a special
+[`checkout`](https://circleci.com/docs/2.0/configuration-reference/#checkout)
+step.
+
+Eventually we are trying to do a `git clone <https://path/to/docs-repository/>`.
+
+## 3. Generate step
+
+Install [`npx`](https://www.npmjs.com/package/npx) to use it for running
+`techdocs-cli`. We are going to use the `techdocs-cli generate` command here.
+
+Take a look at
+[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
+complete command reference, details, and options.
+
+```
+npx techdocs-cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site
+```
+
+`PATH_TO_REPO` should be the location where the prepare step above clones the
+repository.
+
+## 4. Publish step
+
+Take a look at
+[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
+complete command reference, details, and options.
+
+Depending on your cloud storage provider (AWS or Google Cloud), set the
+necessary authentication environment variables.
+
+- [Google Cloud authentication](https://cloud.google.com/storage/docs/authentication#libauth)
+- [AWS authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html)
+
+```
+techdocs-cli publish --directory ./site --publisher-type <awsS3|googleGcs> --bucket-name <bucket> --entity <namespace/kind/name>
+```
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index f5a433fc84..4822ffe397 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -91,6 +91,7 @@
           "features/techdocs/creating-and-publishing",
           "features/techdocs/configuration",
           "features/techdocs/using-cloud-storage",
+          "features/techdocs/configuring-ci-cd",
           "features/techdocs/how-to-guides",
           "features/techdocs/troubleshooting",
           "features/techdocs/faqs"