paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 46 Packages Projects Releases Wiki Activity

1. Use --storage-name instead of bucket name

Browse Source 
2. Prettier ignore description
3. Refer to CLI readme
This commit is contained in:
Himanshu Mishra
2021-01-19 13:18:00 +01:00
parent 6b6bcb549a
commit 3e24d89290
1 changed files with 34 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/configuring-ci-cd.md
+34 -24
View File
@@ -1,8 +1,8 @@
---
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
# prettier-ignore
description: Configuring CI/CD to generate and publish TechDocs sites to cloud storage
---
In the [Recommended deployment setup](./architecture.md#recommended-deployment),
@@ -19,30 +19,37 @@ available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.)
A summary of the instructions below looks like this -
```sh
# This is an example script
# Prepare
REPOSITORY_URL='https://github.com/org/repo'
git clone $REPOSITORY_URL
cd repo
# Generate
npx @techdocs/cli generate --source-dir ./repo --output-dir ./site
npx @techdocs/cli generate
# Publish
npx @techdocs/cli publish --directory ./site --publisher-type awsS3 --bucket-name <bucket> --entity <Namespace/Kind/Name>
# That's it!
npx @techdocs/cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
```
That's it!
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
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`.
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
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.
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.
On GitHub Actions, you can add a step
@@ -57,31 +64,34 @@ 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.
`techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`.
Take a look at
[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
complete command reference, details, and options.
We are going to use the
[`techdocs-cli generate`](https://github.com/backstage/techdocs-cli#generate-techdocs-site-from-a-documentation-project)
command in this step.
```
```sh
npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site
```
`PATH_TO_REPO` should be the location in the file path where the prepare step above clones the
repository.
`PATH_TO_REPO` should be the location in the file path 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, Google Cloud, or Azure), 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)
And then run the
[`techdocs-cli publish`](https://github.com/backstage/techdocs-cli#publish-generated-techdocs-sites)
command.
```sh
npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site
```
npx @techdocs/cli publish --directory ./site --publisher-type <awsS3|googleGcs> --bucket-name <bucket> --entity <namespace/kind/name>
```
The updated TechDocs site built in this workflow is now ready to be served by
the TechDocs plugin in your Backstage app.