Readme and pipeline updates (#315)

* drop workflow_run trigger that seems to cause extra build runs * use docfx:2.59.4, document that main site needs to be started separate from docs site * move to a single gha workflow & use docker args so we can build whole image stack in a PR * "Improve this doc" links are missing #319 --------- Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com>
SteeltoeOSS · Mar 1, 2024 · a117b4f · a117b4f
1 parent 8dc2a5c
commit a117b4f
Show file tree

Hide file tree

Showing 18 changed files with 1,054 additions and 1,072 deletions.
diff --git a/.github/workflows/build-APIdocs-layer.yml b/.github/workflows/build-APIdocs-layer.yml
diff --git a/.github/workflows/build-and-stage.yml b/.github/workflows/build-and-stage.yml
@@ -1,42 +1,127 @@
 name: build-website
 on:
-  workflow_run:
-    workflows: [build-api-docs]
-    types: [completed]
   pull_request:
     branches:
     - main
-    paths:
-    - "*"
-    - "!README.md"
-    - "!docfx/"
-    - "!build-metadata.sh"
-    - "!metadata.conf"
   push:
     branches:
     - main
-    paths:
-    - "*"
-    - "!README.md"
-    - "!docfx/"
-    - "!build-metadata.sh"
-    - "!Dockerfile-metadata"
-    - "!metadata.conf"
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 permissions:
   contents: 'read'
   pull-requests: 'write'
 
 env:
-  IMAGE_TAG: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || github.run_id }}
+  DOCFX_VERSION: 2.59.4
+  DOCFX_SOURCE_BRANCH_NAME: ${{ github.base_ref || github.ref_name }}
+  STEELTOE_V2_VERSION: 2.5.5
+  STEELTOE_V3_VERSION: 3.2.6
+  SITE_IMAGE_VERSION: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || github.run_id }}
 
 jobs:
+  change-detection:
+    name: Detect which layers need to be built, set image versions
+    runs-on: ubuntu-latest
+    # Set job outputs to values from filter step
+    outputs:
+      docfx-layer-changed: ${{ steps.filter.outputs.docfx-layer-changed }}
+      docfx-image-version: ${{ steps.version.outputs.docfx-image-version }}
+      metadata-layer-changed: ${{ steps.filter.outputs.metadata-layer-changed }}
+      metadata-image-version: ${{ steps.version.outputs.metadata-image-version }}
+    steps:
+    - uses: dorny/paths-filter@v3
+      id: filter
+      with:
+        filters: |
+          docfx-layer-changed:
+            - .github/workflows/build-and-stage.yml
+            - 'docfx/**'
+          metadata-layer-changed:
+            - .github/workflows/build-and-stage.yml
+            - Dockerfile-metadata
+            - '/api-*.*'
+            - build-metadata.sh
+            - docfx.json
+    - name: Declare image versions
+      id: version
+      run: |
+        if '${{ steps.filter.outputs.docfx-layer-changed }}' == 'true'
+        then
+          echo "docfx-image-version=${{ github.event_name == 'pull_request' && github.run_id || env.DOCFX_VERSION }}" >> "$GITHUB_OUTPUT"
+        else
+          echo "docfx-image-version=${{ env.DOCFX_VERSION }}" >> "$GITHUB_OUTPUT"
+        fi
+        if '${{ steps.filter.outputs.metadata-layer-changed }}' == 'true'
+        then
+          echo "metadata-image-version=${{ github.event_name == 'pull_request' && github.run_id || env.STEELTOE_VERSIONS }}" >> "$GITHUB_OUTPUT"
+        else
+          echo "metadata-image-version=${{ env.STEELTOE_VERSIONS }}" >> "$GITHUB_OUTPUT"
+        fi
+      env:
+        STEELTOE_VERSIONS: ${{ env.STEELTOE_V2_VERSION }}-${{ env.STEELTOE_V3_VERSION }}
+      shell: bash
+
+  build-push-docfx:
+    name: Build and push docfx layer
+    needs: change-detection
+    if: ${{ needs.change-detection.outputs.docfx-layer-changed }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set DocFX version to use
+      run: echo v${{ env.DOCFX_VERSION }} > docfx/version
+      shell: bash
+
+    - name: Login to container registry
+      uses: docker/login-action@v3
+      with:
+        registry: "${{ vars.DOCKER_REGISTRY }}"
+        username: "${{ secrets.DOCKER_USERNAME }}"
+        password: "${{ secrets.DOCKER_PASSWORD }}"
+
+    - name: Build image
+      run: docker build docfx --file "docfx/Dockerfile" -t ${{ vars.DOCKER_REGISTRY }}/docfx:${{ needs.change-detection.outputs.docfx-image-version }}
+
+    - name: Push image
+      run: docker push ${{ vars.DOCKER_REGISTRY }}/docfx --all-tags
+
+  build-push-metadata:
+    name: Build and push API docs layer
+    needs: [ change-detection, build-push-docfx ]
+    if: ${{ needs.change-detection.outputs.metadata-layer-changed }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set Steeltoe versions to use
+      run: |-
+        echo '2:'${{ env.STEELTOE_V2_VERSION }} > metadata.conf
+        echo '3:'${{ env.STEELTOE_V3_VERSION }} >> metadata.conf
+      shell: bash
+
+    - name: Login to container registry
+      uses: docker/login-action@v3
+      with:
+        registry: "${{ vars.DOCKER_REGISTRY }}"
+        username: "${{ secrets.DOCKER_USERNAME }}"
+        password: "${{ secrets.DOCKER_PASSWORD }}"
+
+    - name: Build image
+      run: docker build --build-arg="DOCFX_IMAGE_VERSION=${{ needs.change-detection.outputs.docfx-image-version }}" . --file "Dockerfile-metadata" -t ${{ vars.DOCKER_REGISTRY }}/documentation-metadata:${{ needs.change-detection.outputs.metadata-image-version }}
+
+    - name: Push image
+      run: docker push ${{ vars.DOCKER_REGISTRY }}/documentation-metadata --all-tags
+
   build-push-deploy:
     name: Build and push documentation image
+    needs: [ change-detection, build-push-docfx, build-push-metadata ]
     environment:
       name: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || vars.STAGING_SLOT_NAME }}
       url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
@@ -59,10 +144,10 @@ jobs:
         password: "${{ secrets.DOCKER_PASSWORD }}"
 
     - name: Build image
-      run: docker build . --file "Dockerfile" -t ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.IMAGE_TAG }}
+      run: docker build --build-arg="METADATA_IMAGE_VERSION=${{ needs.change-detection.outputs.metadata-image-version }}" . --file "Dockerfile" -t ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.SITE_IMAGE_VERSION }}
 
     - name: Push image
-      run: docker push ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.IMAGE_TAG }}
+      run: docker push ${{ vars.DOCKER_REGISTRY }}/documentation --all-tags
 
     - name: If PR, create a new staging slot
       if: ${{ github.event_name == 'pull_request' }}
@@ -74,21 +159,20 @@ jobs:
     - name: Deploy to staging slot
       uses: azure/webapps-deploy@v3
       id: deploy-to-webapp
-      with: 
+      with:
         app-name: ${{ vars.AZURE_WEBAPP_NAME }}
-        images: ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.IMAGE_TAG }}
+        images: ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.SITE_IMAGE_VERSION }}
         slot-name:  ${{ env.SLOT_NAME }}
-    
+
     - name: If PR, comment with the preview link
       if: ${{ github.event_name == 'pull_request' }}
       uses: mshick/add-pr-comment@v2
       with:
         message: |
-          ## Preview link: https://${{ vars.AZURE_WEBAPP_NAME }}-${{ env.SLOT_NAME }}.azurewebsites.net 
-          
+          ## Preview link: https://${{ vars.AZURE_WEBAPP_NAME }}-${{ env.SLOT_NAME }}.azurewebsites.net
+
           - Your changes have been deployed to the preview site. The preview site will update as you add more commits to this branch.
           - The preview link is shareable, but will be deleted when the pull request is merged or closed.
 
           > *This is an automated message.*
         repo-token: ${{ secrets.GITHUB_TOKEN }}
-
diff --git a/.github/workflows/build-base-layer.yml b/.github/workflows/build-base-layer.yml
diff --git a/.github/workflows/pr-cleanup.yml b/.github/workflows/pr-cleanup.yml
@@ -16,7 +16,7 @@ jobs:
       uses: azure/login@v1
       with:
         creds: ${{ secrets.AZURE_CREDENTIALS }}
-    
+
     - name: Delete slot on staging site
       run: az webapp deployment slot delete --resource-group ${{ vars.AZURE_RESOURCE_GROUP }} --name ${{ vars.AZURE_WEBAPP_NAME}} --slot ${{ env.SLOT_NAME }}
 
@@ -29,4 +29,4 @@ jobs:
         with:
           environment: "pr-${{ github.event.number }}"
           token: ${{ secrets.GITHUB_TOKEN }}
-          onlyRemoveDeployments: true
+          onlyRemoveDeployments: true
diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,6 @@
-FROM steeltoe.azurecr.io/documentation-metadata:2.5.5-3.2.6 AS build
+# example --build-arg="METADATA_IMAGE_VERSION=2.5.5-3.2.6"
+ARG METADATA_IMAGE_VERSION
+FROM steeltoe.azurecr.io/documentation-metadata:${METADATA_IMAGE_VERSION} AS build
 WORKDIR /docs
 COPY . .
 RUN docfx build -o /built-docs --globalMetadataFiles main-site.json

diff --git a/Dockerfile-metadata b/Dockerfile-metadata
@@ -1,4 +1,6 @@
-FROM steeltoe.azurecr.io/docfx:2.59.2
+# example --build-arg="DOCFX_IMAGE_VERSION=2.59.4"
+ARG DOCFX_IMAGE_VERSION
+FROM steeltoe.azurecr.io/docfx:${DOCFX_IMAGE_VERSION}
 WORKDIR /docs
 COPY . .
 RUN ["chmod", "+x", "./build-metadata.sh"]