tyk-docs.yml

# yamllint disable rule:line-length
---
name: Tyk Docs sync

run-name: '[${{ inputs.jira }}] ${{ github.actor }} running tyk-docs sync'

# This workflow builds the documentation for a release.
# It uses the following external dependencies:
#
# Generator: tyk-config-info-generator
# Provides: tyk-docs/content/shared/gateway-config.md
# Source: https://github.com/TykTechnologies/tyk-config-info-generator
#
# Generator: schema-gen markdown
# Provides: tyk-docs/content/shared/x-tyk-gateway.md
# Source: https://github.com/TykTechnologies/exp/tree/main/cmd/schema-gen
#
# The schema-gen tool is provided using the tykio/ci-tools docker image.
# To rebuild that docker image if required, trigger an update via:
#
# https://github.com/TykTechnologies/tyk-github-actions/actions/workflows/ci-docker-tools.yml
#
# You can test the schema-gen docs generator in this repo: pkg/model/Taskfile.yml;
# Running the taskfile with `task` will generate gateway/README.md, among other files.

on:  # yamllint disable-line rule:truthy
  workflow_dispatch:
    inputs:
      jira:
        description: JIRA ID (MM-NNNN or permalink)
        required: true
        default: ''
      sync-gateway:
        description: Include Gateway
        type: boolean
      sync-dashboard:
        description: Include Dashboard
        type: boolean
      sync-pump:
        description: Include Pump
        type: boolean
      sync-mdcb:
        description: Include MDCB
        type: boolean
      release:
        description: 'Release version'
        type: choice
        options:
          - 'master'
          - '5.3'
          - '5.2'
          - '5.1'
          - '5.0 LTS'
      source:
        description: 'Override source branch'
        default: ''
      destination:
        description: 'Override destination branch'
        default: ''
      branch-suffix:
        description: 'Branch suffix to append to PR branch name (to prevent collisions on multiple PRs/ticket)'
        required: true
        default: 'docs'
      note:
        description: 'Note for PR'
        required: true
        default: '<none>'

env:
  GOPRIVATE: github.com/TykTechnologies
  configInfoGeneratorBranch: main

jobs:
  sanitize:
    name: Sanitize inputs
    runs-on: ubuntu-latest
    outputs:
      docsBranch: ${{ steps.collect.outputs.docsBranch }}
      repoBranch: ${{ steps.collect.outputs.repoBranch }}
      jira: ${{ steps.collect.outputs.jira }}
    steps:
      - name: Sanitize JIRA input
        run: |
          jira=$(echo '${{ github.event.inputs.jira }}' | sed -e 's/?.*//g' | xargs -n1 basename)
          if [ "$jira" == *"-"* ]; then
             echo "No valid JIRA ID found (no dash in JIRA ID)"
             exit 1
          fi
          echo "jira=$jira" >> $GITHUB_ENV

      - if: github.event.inputs.release == 'master'
        run: |
             echo "docsBranch=master" >> $GITHUB_ENV
             echo "repoBranch=master" >> $GITHUB_ENV

      - if: github.event.inputs.release == '5.0 LTS'
        run: |
             echo "docsBranch=release-5" >> $GITHUB_ENV
             echo "repoBranch=release-5-lts" >> $GITHUB_ENV

      - if: github.event.inputs.release == '5.1'
        run: |
             echo "docsBranch=release-5.1" >> $GITHUB_ENV
             echo "repoBranch=release-5.1" >> $GITHUB_ENV

      - if: github.event.inputs.release == '5.2'
        run: |
             echo "docsBranch=release-5.2" >> $GITHUB_ENV
             echo "repoBranch=release-5.2" >> $GITHUB_ENV

      - if: github.event.inputs.release == '5.3'
        run: |
             echo "docsBranch=release-5.3" >> $GITHUB_ENV
             echo "repoBranch=release-5.3" >> $GITHUB_ENV

      - if: github.event.inputs.source != ''
        run: echo "repoBranch=${{ github.event.inputs.source }}" >> $GITHUB_ENV

      - if: github.event.inputs.destination != ''
        run: echo "docsBranch=${{ github.event.inputs.destination }}" >> $GITHUB_ENV

      - id: collect
        run: |
             echo "jira=${{ env.jira }}" >> $GITHUB_OUTPUT
             echo "docsBranch=${{ env.docsBranch }}" >> $GITHUB_OUTPUT
             echo "repoBranch=${{ env.repoBranch }}" >> $GITHUB_OUTPUT

  gateway:
    needs: [sanitize]
    name: Gateway docs
    if: ${{ github.event.inputs.sync-gateway == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Gateway
        uses: actions/checkout@v4.2.1
        with:
          fetch-depth: 1
          repository: TykTechnologies/tyk
          ref: ${{ needs.sanitize.outputs.repoBranch }}
          path: ./tyk

      - name: 'Extract tykio/ci-tools:latest'
        uses: shrink/actions-docker-extract@v3.0.1
        with:
          image: tykio/ci-tools:latest
          path: /usr/local/bin/.
          destination: /usr/local/bin

      - run: mkdir -p gateway-docs/

      - name: Generate x-tyk-gateway docs
        working-directory: ./tyk/apidef/oas
        run: |
          schema-gen extract -o - | schema-gen markdown -i - \
                                                        --root XTykAPIGateway \
                                                        --skip "OldOAS,APIDef,OAS,TykExtensionConfigParams" \
                                                        --title "## Tyk OAS API Definition Object" \
                                                        --replace "model.ObjectID=string,apidef.MiddlewareDriver=string,apidef.IdExtractorSource=string,apidef.IdExtractorType=string,apidef.RequestInputType=string,apidef.AuthTypeEnum=string,[]osin.AuthorizeRequestType=[]string" \
                                                        --heading-format "### **%s**" \
                                                        --trim "Tyk classic API definition" \
                                                        -o ../../../gateway-docs/x-tyk-gateway.md

      - name: Generate docs
        run: |
          cp ./tyk/swagger.yml gateway-docs/gateway-swagger.yml

      - name: Store docs
        uses: actions/upload-artifact@v4.4.1
        with:
          name: gateway-docs
          path: gateway-docs

  dashboard:
    needs: [sanitize]
    name: Dashboard docs
    if: ${{ github.event.inputs.sync-dashboard == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Dashboard
        uses: actions/checkout@v4.2.1
        with:
          token: ${{ secrets.ORG_GH_TOKEN }}
          fetch-depth: 1
          repository: TykTechnologies/tyk-analytics
          ref: ${{ needs.sanitize.outputs.repoBranch }}
          path: ./tyk-analytics

      - name: Generate docs
        run: |
          mkdir -p dashboard-docs/
          cp ./tyk-analytics/swagger.yml dashboard-docs/dashboard-swagger.yml
          cp ./tyk-analytics/swagger-admin.yml dashboard-docs/dashboard-admin-swagger.yml

      - name: Store docs
        uses: actions/upload-artifact@v4.4.1
        with:
          name: dashboard-docs
          path: dashboard-docs

  mdcb:
    needs: [sanitize]
    name: MDCB docs
    if: ${{ github.event.inputs.sync-mdcb == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout MDCB
        uses: actions/checkout@v4.2.1
        with:
          token: ${{ secrets.ORG_GH_TOKEN }}
          fetch-depth: 1
          repository: TykTechnologies/tyk-sink
          ref: ${{ needs.sanitize.outputs.repoBranch }}
          path: ./tyk-sink

      - name: Generate docs
        run: |
          mkdir -p mdcb-docs/
          cp ./tyk-sink/swagger.yml mdcb-docs/mdcb-swagger.yml

      - name: Store docs
        uses: actions/upload-artifact@v4.4.1
        with:
          name: mdcb-docs
          path: mdcb-docs

  configs:
    needs: [sanitize]
    name: Configuration docs
    runs-on: ubuntu-latest
    steps:
      - name: Install Config Generator
        uses: actions/checkout@v4.2.1
        with:
          repository: TykTechnologies/tyk-config-info-generator
          path: ./tyk-config-info-generator
          token: ${{ secrets.ORG_GH_TOKEN }}
          ref: ${{ env.configInfoGeneratorBranch }}

      - name: Set up env
        run: |
             mkdir -p $GITHUB_WORKSPACE/config-docs/
             echo "repoBranch=${{ needs.sanitize.outputs.repoBranch }}" >> $GITHUB_ENV
             echo "docsBranch=${{ needs.sanitize.outputs.docsBranch }}" >> $GITHUB_ENV

      - name: Sync Gateway
        working-directory: ./tyk-config-info-generator/src
        if: ${{ github.event.inputs.sync-gateway == 'true' }}
        run: |
          repo=gateway
          branch=$repoBranch
          dest=$GITHUB_WORKSPACE/config-docs/$repo-config.md

          sudo TOKEN=${{ secrets.ORG_GH_TOKEN }} node app.js $repo:$branch
          cp /node/home/tyk-config-info-generator/info/$branch/gateway.md $dest

      - name: Sync Dashboard
        working-directory: ./tyk-config-info-generator/src
        if: ${{ github.event.inputs.sync-dashboard == 'true' }}
        run: |
          repo=dashboard
          branch=$repoBranch
          dest=$GITHUB_WORKSPACE/config-docs/$repo-config.md

          sudo TOKEN=${{ secrets.ORG_GH_TOKEN }} node app.js $repo:$branch
          cp /node/home/tyk-config-info-generator/info/$branch/$repo.md $dest

      - name: Sync Pump
        working-directory: ./tyk-config-info-generator/src
        if: ${{ github.event.inputs.sync-pump == 'true' }}
        run: |
          repo=pump
          branch=${{ github.event.inputs.source || 'master' }}
          dest=$GITHUB_WORKSPACE/config-docs/$repo-config.md

          sudo TOKEN=${{ secrets.ORG_GH_TOKEN }} node app.js $repo:$branch
          cp /node/home/tyk-config-info-generator/info/$branch/$repo.md $dest

      - name: Sync MDCB
        working-directory: ./tyk-config-info-generator/src
        if: ${{ github.event.inputs.sync-mdcb == 'true' }}
        run: |
          repo=mdcb
          branch=${{ github.event.inputs.source || 'master' }}
          dest=$GITHUB_WORKSPACE/config-docs/$repo-config.md

          sudo TOKEN=${{ secrets.ORG_GH_TOKEN }} node app.js $repo:$branch
          cp /node/home/tyk-config-info-generator/info/$branch/$repo.md $dest

      - name: Store docs
        uses: actions/upload-artifact@v4.4.1
        with:
          name: config-docs
          path: config-docs

  finish:
    name: Open PR against tyk-docs
    needs: [sanitize, configs, dashboard, gateway]
    if: ${{ always() }}
    runs-on: ubuntu-latest
    steps:
      - name: Restore artifacts
        uses: actions/download-artifact@v4.1.8

      - name: Set up env
        run: |
             echo "jira=${{ needs.sanitize.outputs.jira }}" >> $GITHUB_ENV
             echo "target=${{ needs.sanitize.outputs.docsBranch }}" >> $GITHUB_ENV

      - name: Checkout Docs
        uses: actions/checkout@v4.2.1
        with:
          fetch-depth: 1
          repository: TykTechnologies/tyk-docs
          path: ./tyk-docs
          ref: ${{ needs.sanitize.outputs.docsBranch }}

      - name: Write out docs
        run: |
             [ -d "gateway-docs" ]   && cp gateway-docs/*.yml ./tyk-docs/tyk-docs/assets/others/
             [ -d "gateway-docs" ]   && cp gateway-docs/x-tyk-gateway.md ./tyk-docs/tyk-docs/content/shared/
             [ -d "dashboard-docs" ] && cp dashboard-docs/*.yml ./tyk-docs/tyk-docs/assets/others/
             [ -d "mdcb-docs" ]      && cp mdcb-docs/*.yml ./tyk-docs/tyk-docs/assets/others/
             [ -d "config-docs" ]    && cp config-docs/* ./tyk-docs/tyk-docs/content/shared/

      - name: Raise tyk-docs PR
        uses: peter-evans/create-pull-request@v7.0.5
        with:
          token: ${{ secrets.ORG_GH_TOKEN }}
          commit-message: Import config/docs
          title: '[${{ env.jira }}] Update documentation for ${{ github.event.inputs.release }}'
          body: |
            Triggered by: ${{ github.actor }}

            Included:

            Tyk Gateway: ${{ github.event.inputs.sync-gateway }}
            Tyk Dashboard: ${{ github.event.inputs.sync-dashboard }}
            Tyk MDCB ${{ github.event.inputs.sync-mdcb }}
            Tyk Pump ${{ github.event.inputs.sync-pump }}

            Intended for: ${{ github.event.inputs.release }}
            Changes sourced from: ${{ needs.sanitize.outputs.repoBranch }}
            Config info generator branch: ${{ env.configInfoGeneratorBranch }}

            Note: ${{ github.event.inputs.note }} (branch suffix: ${{ github.event.inputs.branch-suffix }})

            JIRA: https://tyktech.atlassian.net/browse/${{ env.jira }}
          branch: update/${{ env.jira }}/release-${{ env.target }}-${{ github.event.inputs.branch-suffix }}
          path: ./tyk-docs
          delete-branch: true