api-docs-repo.yaml

name: Generate CRD docs
on:
  workflow_dispatch:
  # no content, allows manual triggering

  schedule:
    # 5:35 pm every Sunday (UTC)
    # to ensure the docs are never too stale
    - cron: "35 17 * * 0"

jobs:
  gen-crd-docs:

    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: read

    # Only run this scheduled job on the main repo, it can't work elsewhere
    if: ${{ github.repository == 'Azure/azure-service-operator' }}
    
    steps:
      - name: Create token
        uses: actions/create-github-app-token@v1
        id: app-token
        with:
          # required
          app-id: ${{ secrets.AUTOMATION_ID }}
          private-key: ${{ secrets.AUTOMATION_KEY }}
          
      - name: Checkout code
        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pinned to 4.1.7
        with:
          ref: main

      - name: Create Branch
        uses: peterjgrainger/action-create-branch@10c7d268152480ae859347db45dc69086cef1d9c # pinned to v3.0.0
        env:
          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
        with:
          branch: ${{ format('bot/update-api-docs-{0}', github.run_number) }}

      - name: Checkout code
        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pinned to 4.1.7
        with:
          ref: ${{ format('bot/update-api-docs-{0}', github.run_number) }}
          fetch-depth: 0 # required to access tags
          submodules: "true"

      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # pinned to v3.3.0
        with:
          registry: docker.pkg.github.com # ghcr.io not yet enabled for Azure org
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build devcontainer image
        # We must issue a manual pull before the build so the image gets copied locally, because
        # docker.pkg.github.com is not a valid Docker registry and doesn't work with --cache-from,
        # however, `docker pull` will fall back to other methods that do work and get the image loaded.
        #
        # This message comes from "docker pull":
        #
        # Run docker pull docker.pkg.github.com/azure/azure-service-operator/aso-devcontainer:latest
        # WARNING: ⚠️ Failed to pull manifest by the resolved digest. This registry does not
        #  appear to conform to the distribution registry specification; falling back to
        #  pull by tag.  This fallback is DEPRECATED, and will be removed in a future
        #  release.  Please contact admins of https://docker.pkg.github.com. ⚠️
        #
        # See: https://github.com/moby/moby/issues/41687#issuecomment-733826074 and related issues
        run: |
          docker pull docker.pkg.github.com/azure/azure-service-operator/aso-devcontainer:latest
          docker build --cache-from docker.pkg.github.com/azure/azure-service-operator/aso-devcontainer:latest --tag devcontainer:latest .devcontainer
        env:
          DOCKER_BUILDKIT: 1

      - name: Run devcontainer image
        id: devcontainer
        run: |
          container_id=$(docker create -w /workspace -v $GITHUB_WORKSPACE:/workspace -v /var/run/docker.sock:/var/run/docker.sock devcontainer:latest)
          docker start "$container_id"
          echo "container_id=$container_id" >> $GITHUB_ENV

      - name: Generate API docs
        run: |
          container_id=${{ env.container_id }}
          docker exec "$container_id" task controller:gen-crd-docs

      # After generating the API docs (above), regenerate our index files as now new CRDs can be linked to their docs
      # Have to force this to ensure the index files are updated
      - name: Generate Index files
        run: |
          container_id=${{ env.container_id }}
          docker exec "$container_id" task controller:generate-types

      # Workaround for getting "Permission denied" errors when trying to stage files
      - name: Take Ownership
        run: sudo chown -R $USER:$USER .


      # Generating docs can take so long that the original token expires, so we create a new one
      # and use that to create the PR
      - name: Create token for PR
        uses: actions/create-github-app-token@v1
        id: pr-token
        with:
          # required
          app-id: ${{ secrets.AUTOMATION_ID }}
          private-key: ${{ secrets.AUTOMATION_KEY }}

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f # pinned to v7.0.5
        with:
          token: ${{ steps.pr-token.outputs.token }}
          commit-message: Update API Docs
          branch: ${{ format('bot/update-api-docs-{0}', github.run_number) }}
          base: main
          delete-branch: true
          title: "[Automated] Add API Docs"
          body: |
            Update API documentation for ASO Custom Resource Definitions

            Auto-generated by [create-pull-request][1]

            [1]: https://github.com/peter-evans/create-pull-request
          labels: |
            automated pr