From 94e8011b972f077fa893645c911e599fb3ccc94e Mon Sep 17 00:00:00 2001 From: swibrow <15628653+swibrow@users.noreply.github.com> Date: Fri, 13 Mar 2026 12:41:08 +0100 Subject: [PATCH] feat: add techdocs-publish reusable workflow Adds a reusable workflow for building and publishing Backstage TechDocs to S3, along with test workflow and fixtures. --- .github/workflows/_test-techdocs.yaml | 45 +++++++++++ .github/workflows/techdocs-publish.yaml | 85 ++++++++++++++++++++ docs/workflows/techdocs-publish.md | 102 ++++++++++++++++++++++++ tests/techdocs/docs/index.md | 3 + tests/techdocs/mkdocs.yaml | 5 ++ tests/techdocs/requirements.txt | 2 + 6 files changed, 242 insertions(+) create mode 100644 .github/workflows/_test-techdocs.yaml create mode 100644 .github/workflows/techdocs-publish.yaml create mode 100644 docs/workflows/techdocs-publish.md create mode 100644 tests/techdocs/docs/index.md create mode 100644 tests/techdocs/mkdocs.yaml create mode 100644 tests/techdocs/requirements.txt diff --git a/.github/workflows/_test-techdocs.yaml b/.github/workflows/_test-techdocs.yaml new file mode 100644 index 0000000..7c53292 --- /dev/null +++ b/.github/workflows/_test-techdocs.yaml @@ -0,0 +1,45 @@ +on: + pull_request: + branches: + - main + paths: + - ".github/workflows/_test-techdocs.yaml" + - ".github/workflows/techdocs-publish.yaml" + - "tests/techdocs/**" + +jobs: + test_techdocs_generate: + name: Test TechDocs Generate + runs-on: ubuntu-latest + defaults: + run: + working-directory: tests/techdocs + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.x" + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + + - name: Install techdocs-cli + run: npm install -g @techdocs/cli + + - name: Generate TechDocs + run: techdocs-cli generate --no-docker + + - name: Verify output + run: | + test -d site + test -f site/index.html diff --git a/.github/workflows/techdocs-publish.yaml b/.github/workflows/techdocs-publish.yaml new file mode 100644 index 0000000..98a4b03 --- /dev/null +++ b/.github/workflows/techdocs-publish.yaml @@ -0,0 +1,85 @@ +name: Publish TechDocs to S3 +on: + workflow_call: + inputs: + entity_name: + description: "Backstage entity name (e.g. dai-handbook)" + type: string + required: true + entity_namespace: + description: "Backstage entity namespace" + type: string + default: "default" + entity_kind: + description: "Backstage entity kind" + type: string + default: "Component" + requirements_file: + description: "Path to the requirements.txt file" + type: string + default: "requirements.txt" + python_version: + description: "Python version" + type: string + default: "3.x" + node_version: + description: "Node version for techdocs-cli" + type: string + default: "20" + s3_bucket_name: + description: "S3 bucket name for TechDocs storage" + type: string + required: true + aws_region: + description: "AWS region" + type: string + default: "eu-west-1" + aws_role_arn: + description: "AWS OIDC role ARN for assuming credentials" + type: string + required: true + +jobs: + publish: + name: Build & Publish TechDocs + runs-on: ubuntu-latest + permissions: + id-token: write + contents: read + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + + - name: Set up Python ${{ inputs.python_version }} + uses: actions/setup-python@v6 + with: + python-version: ${{ inputs.python_version }} + + - name: Set up Node ${{ inputs.node_version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ inputs.node_version }} + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r ${{ inputs.requirements_file }} + + - name: Install techdocs-cli + run: npm install -g @techdocs/cli + + - name: Build TechDocs + run: techdocs-cli generate --no-docker + + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ inputs.aws_role_arn }} + aws-region: ${{ inputs.aws_region }} + + - name: Publish TechDocs + run: | + techdocs-cli publish \ + --publisher-type awsS3 \ + --storage-name ${{ inputs.s3_bucket_name }} \ + --entity ${{ inputs.entity_namespace }}/${{ inputs.entity_kind }}/${{ inputs.entity_name }} diff --git a/docs/workflows/techdocs-publish.md b/docs/workflows/techdocs-publish.md new file mode 100644 index 0000000..38009f0 --- /dev/null +++ b/docs/workflows/techdocs-publish.md @@ -0,0 +1,102 @@ +--- +title: Publish TechDocs to S3 +--- + +## Description + + +### Inputs + +| name | description | type | required | default | +| --- | --- | --- | --- | --- | +| `entity_name` |

Backstage entity name (e.g. dai-handbook)

| `string` | `true` | `""` | +| `entity_namespace` |

Backstage entity namespace

| `string` | `false` | `default` | +| `entity_kind` |

Backstage entity kind

| `string` | `false` | `Component` | +| `requirements_file` |

Path to the requirements.txt file

| `string` | `false` | `requirements.txt` | +| `python_version` |

Python version

| `string` | `false` | `3.x` | +| `node_version` |

Node version for techdocs-cli

| `string` | `false` | `20` | +| `s3_bucket_name` |

S3 bucket name for TechDocs storage

| `string` | `true` | `""` | +| `aws_region` |

AWS region

| `string` | `false` | `eu-west-1` | +| `aws_role_arn` |

AWS OIDC role ARN for assuming credentials

| `string` | `true` | `""` | + + + + + + + +### Usage + +```yaml +jobs: + job1: + uses: dnd-it/github-workflows/.github/workflows/techdocs-publish.yaml@v2 + with: + entity_name: + # Backstage entity name (e.g. dai-handbook) + # + # Type: string + # Required: true + # Default: "" + + entity_namespace: + # Backstage entity namespace + # + # Type: string + # Required: false + # Default: default + + entity_kind: + # Backstage entity kind + # + # Type: string + # Required: false + # Default: Component + + requirements_file: + # Path to the requirements.txt file + # + # Type: string + # Required: false + # Default: requirements.txt + + python_version: + # Python version + # + # Type: string + # Required: false + # Default: 3.x + + node_version: + # Node version for techdocs-cli + # + # Type: string + # Required: false + # Default: 20 + + s3_bucket_name: + # S3 bucket name for TechDocs storage + # + # Type: string + # Required: true + # Default: "" + + aws_region: + # AWS region + # + # Type: string + # Required: false + # Default: eu-west-1 + + aws_role_arn: + # AWS OIDC role ARN for assuming credentials + # + # Type: string + # Required: true + # Default: "" +``` + + +## Example + +## FAQ diff --git a/tests/techdocs/docs/index.md b/tests/techdocs/docs/index.md new file mode 100644 index 0000000..07a0fe9 --- /dev/null +++ b/tests/techdocs/docs/index.md @@ -0,0 +1,3 @@ +# TechDocs Test + +This is a test page for the TechDocs publish workflow. diff --git a/tests/techdocs/mkdocs.yaml b/tests/techdocs/mkdocs.yaml new file mode 100644 index 0000000..96f85ab --- /dev/null +++ b/tests/techdocs/mkdocs.yaml @@ -0,0 +1,5 @@ +site_name: TechDocs Test +docs_dir: docs/ + +plugins: + - techdocs-core diff --git a/tests/techdocs/requirements.txt b/tests/techdocs/requirements.txt new file mode 100644 index 0000000..14b69f5 --- /dev/null +++ b/tests/techdocs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs~=1.6.1 +mkdocs-techdocs-core~=1.4.2