Make it easy to use techdocs-cli in CI

[taras]

Motivation

I need to integrate techdocs-cli into our Jenkins pipeline. We have the ability to run any docker container image. Other CI tools like GitHub Actions and CircleCI also have the same ability. We can also install executables as part of the CI process but this adds build time overhead to each CI job. Instead, I would like to be able use techdoc-cli that is distributed as a container image.

I created a spike to see what this would look here.

Approach

You can build this image with,

cd docker;
docker build -t techdocs-cli .

This will create a local image that you can use to run your CLI. To use this image,

cd your_project;
docker run -v $(pwd):/workspace/ build --no-docker

This will execute execute build command on your techdocs-cli within the docker container.

This base image could be used to create a GitHub Action for techdocs-cli. This would simplify the workflow script from

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

to something like this,

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

      - name: Publish docs site
        uses: backstage/techdocs-cli
        with:
          args: |
            publish --publisher-type awsS3 \
              --storage-name ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}--entity \
              default/Component/my-doc-entity

Note: this probably wouldn't be the arguments that the action would accept but it makes for a better comparison.

[OrkoHunter]

Cool, I think it's worth creating the image since it makes the workflow easier! In your simplified GitHub actions example, I think we'll still have to do the "generate" bit.

[brizzbuzz]

So I'm curious about the choice to make techdocs-cli the entrypoint... if you just made this bash then the user could run consecutive commands against a container... I'm using codefresh so it will be a bit different but then you can do something like this

  generate-and-publish-docs:
    title: Publish Docs to S3 Bucket
    stage: deploy
    image: backstage-techdocs
    working_directory: "${{clone}}"
    commands:
      - techdocs-cli generate --no-docker
      - techdocs-cli publish --publisher-type awsS3 --storage-name bucket --entity entity 

[OrkoHunter]

Aha, that's an interesting approach!

[taras]

@rgbrizzlehizzle that would work too. I'm going to set it up with our Jenkins setup and see how it works.

[Fox32]

We build such an image on our own to run it on Jenkins and on GitHub Actions (seems to be much faster than installing everything). This is what we are using:

FROM spotify/techdocs:v0.2.0

RUN apk add --update nodejs npm && npm install -g @techdocs/cli

# The jenkins requires that no entrypoint is set
ENTRYPOINT [""]

Is there anything blocking us from providing a spotify/techdocs-cli image?