Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: configuring-ci-cd.md

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 , 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 . The steps here target all kinds of CI providers (GitHub Actions, CircleCI, 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 REPOSITORY_URL='https://github.com/org/repo' git clone $REPOSITORY_URL cd repo npm install -g @techdocs/cli pip install "mkdocs-techdocs-core==1.*" techdocs-cli generate --no-docker techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name> ``` That's it! Take a look at for the complete command reference, details, and options. 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. 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 . On CircleCI, you can add a special step. Eventually we are trying to do a `git clone <https://path/to/docs-repository/>`. Install to use it for running `techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`. We are going to use the command in this step. ```sh npx @techdocs/cli generate --no-docker --source-dir PATHTOREPO --output-dir ./site ``` `PATHTOREPO` should be the location in the file path where the prepare step above clones the repository. Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the necessary authentication environment variables. And then run the command. ```sh npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site ``` The updated TechDocs site built in this workflow is now ready to be served by the TechDocs plugin in your Backstage app. Here is an example workflow using GitHub Actions CI and AWS S3 storage. You can use any CI and any other . Add a `.github/workflows/techdocs.yml` file in your like this - ```yaml name: Publish TechDocs Site on: push: branches: [main] jobs: publish-techdocs-site: runs-on: ubuntu-latest env: TECHDOCSS3BUCKETNAME: ${{ secrets.TECHDOCSS3BUCKETNAME }} AWSACCESSKEYID: ${{ secrets.AWSACCESSKEYID }} AWSSECRETACCESSKEY: ${{ secrets.AWSSECRETACCESSKEY }} AWSREGION: ${{ secrets.AWSREGION }} ENTITY_NAMESPACE: 'default' ENTITY_KIND: 'Component' ENTITY_NAME: 'my-doc-entity' steps: name: Checkout code uses: actions/checkout@v3 uses: actions/setup-node@v3 uses: actions/setup-python@v4 with: python-version: '3.9' name: setup java uses: actions/setup-java@v3 with: distribution: 'zulu' java-version: '11' name: download, validate, install plantuml and its dependencies run: | curl -o plantuml.jar -L http://sourceforge.net/projects/plantuml/files/plantuml.1.2021.4.jar/download echo "be498123d20eaea95a94b174d770ef94adfdca18 plantuml.jar" | sha1sum -c - mv plantuml.jar /opt/plantuml.jar mkdir -p "$HOME/.local/bin" echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> "$HOME/.local/bin/plantuml" chmod +x "$HOME/.local/bin/plantuml" echo "$HOME/.local/bin" >> $GITHUB_PATH sudo apt-get install -y graphviz 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==1.* name: Generate docs site run: techdocs-cli generate --no-docker --verbose name: Publish docs site run: techdocs-cli publish --publisher-type awsS3 --storage-name $TECHDOCSS3BUCKETNAME --entity $ENTITYNAMESPACE/$ENTITYKIND/$ENTITYNAME ``` 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.