Polish CI/CD workflows (#31)

* Polish CI/CD workflows

Signed-off-by: Michel Hidalgo <[email protected]>

* Update .github/workflows/cd.yml

Co-authored-by: Andrew Messing <[email protected]>

* Update .github/workflows/cd.yml

Co-authored-by: Andrew Messing <[email protected]>

* Update .github/workflows/mirror.yml

Co-authored-by: Andrew Messing <[email protected]>

* Update .github/workflows/mirror-release.yml

Co-authored-by: Andrew Messing <[email protected]>

---------

Signed-off-by: Michel Hidalgo <[email protected]>
Co-authored-by: Andrew Messing <[email protected]>

Author: mhidalgo-bdai

.github/workflows/cd.yml

@@ -1,3 +1,4 @@
+# This workflow automatically releases binaries upon tagging.
 name: bosdyn_msgs CD
 
 on:
@@ -10,7 +11,6 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  # Use docker.io for Docker Hub if empty
   REGISTRY: ghcr.io
   # github.repository as <account>/<repo>
   BUNDLER_IMAGE_NAME: bdaiinstitute/bosdyn_msgs_bundler
@@ -39,7 +39,7 @@ jobs:
         uses: actions/checkout@v3
         with:
           submodules: true
-      - name: Set up QEMU
+      - name: Set up QEMU  # as virtualization is necessary to build container images
         uses: docker/setup-qemu-action@v3
       - name: Setup Docker buildx  # to workaround: https://github.com/docker/build-push-action/issues/461
         uses: docker/setup-buildx-action@79abd3f86f79a9d68a23c75a09a9a85889262adf
@@ -49,7 +49,7 @@ jobs:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build and push by digest (may be cached)
+      - name: Build and push by digest (may be cached)  # instead of tagging -- images will be merged in the next job
         uses: docker/build-push-action@ac9327eae2b366085ac7f6a2d02df8aa8ead720a  # https://github.com/docker/build-push-action
         id: build
         with:
@@ -71,7 +71,7 @@ jobs:
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
-  merge-container-images:
+  merge-container-images:  # so that a unique tag + platform dictate which container image is used
     name: Merge all bundler images
     runs-on: ubuntu-latest
     needs: [build-container-images]
@@ -109,7 +109,7 @@ jobs:
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< '${{ steps.meta.outputs.json }}') \
             $(printf '${{ env.REGISTRY }}/${{ env.BUNDLER_IMAGE_NAME }}@sha256:%s ' *)
-  build-bundles:
+  build-bundles:  # using containers on native architectures for speed
     strategy:
       matrix:
         config:
@@ -141,7 +141,6 @@ jobs:
       - name: Download bundles
         uses: actions/download-artifact@v4
         with:
-          # With no `name` specified all artifacts for the run are downloaded.
           pattern: '*-bundle-artifact'
           merge-multiple: true
       - name: Release bundles to Github

.github/workflows/ci.yml

@@ -2,6 +2,8 @@ name: bosdyn_msgs CI
 
 on:
   pull_request:
+    branches:
+      - main
   push:
     branches:
       - main
@@ -20,7 +22,7 @@ jobs:
       fail-fast: false
       matrix:
         config:
-        - { runner: "ubuntu-22-04-large-runner", image: "ros:humble-ros-base-jammy", arch: "amd64" }
+        - { runner: "k8s-n1-standard-16", image: "ros:humble-ros-base-jammy", arch: "amd64" }
         - { runner: "k8s-t2a-standard-16", image: "arm64v8/ros:humble-ros-base-jammy", arch: "arm64" }
     name: Build and test bosdyn_msgs packages for ${{ matrix.config.arch }}
     runs-on: ${{ matrix.config.runner }}
@@ -32,16 +34,14 @@ jobs:
         with:
           path: src/bosdyn_msgs
           submodules: true
-      
       - name: Install dependencies
         run: |
           apt update && apt install -y python3-pip
           export PIP_CONSTRAINT=src/bosdyn_msgs/pip-constraint.txt
           rosdep update && rosdep install -i -y --from-path src
-      
       - name: Build and run tests for ${{ matrix.config.arch }}
         run: |
           source /opt/ros/humble/setup.bash
           colcon build --symlink-install --packages-up-to bosdyn_msgs
           colcon test --event-handlers console_direct+ --packages-up-to bosdyn_msgs
-          colcon test-result --all --verbose
+          colcon test-result --all --verbose  # to ensure the job fails if any test does

.github/workflows/mirror-release.yml

@@ -1,19 +1,20 @@
+# This workflow keeps the public repository releases in sync with those in the private repository
 name: bosdyn_msgs release mirroring
 
 on:
-  workflow_dispatch:
-  workflow_run:
+  workflow_dispatch:  # to enable manual release mirroring
+  workflow_run:  # to trigger release mirroring after an automated release
     workflows: [bosdyn_msgs CD]
     types: [completed]
-  release:
+  release:  # to trigger release mirroring after a manual release
     types: [published]
 
 env:
   # github.repository as <account>/<repo>
   MIRROR_REPOSITORY: bdaiinstitute/bosdyn_msgs
 
 jobs:
-  mirror-latest-release:
+  mirror-latest-release:  # only applies to workflow events
     name: Mirror latest bosdyn_msgs release
     runs-on: ubuntu-latest
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
@@ -24,7 +25,7 @@ jobs:
         uses: robinraju/[email protected]
         id: download
         with:
-          latest: true
+          latest: true  # release tag unknown, default to latest
           fileName: '*.run'
       - name: Create mirror release
         uses: softprops/action-gh-release@v1
@@ -34,7 +35,7 @@ jobs:
           token: ${{ secrets.MIRROR_PAT }}
           tag_name: ${{ steps.download.outputs.tag_name }}
           files: '*.run'
-  mirror-published-release:
+  mirror-published-release:  # only applies to release events
     name: Mirror published bosdyn_msgs release
     runs-on: ubuntu-latest
     if: ${{ github.event_name == 'release' }}
@@ -45,7 +46,7 @@ jobs:
         uses: robinraju/[email protected]
         id: download
         with:
-          tag: ${{ github.ref_name }}
+          tag: ${{ github.ref_name }}  # use the release tag
           fileName: '*.run'
       - name: Create mirror release
         uses: softprops/action-gh-release@v1

.github/workflows/mirror.yml

@@ -1,3 +1,4 @@
+# This workflow keeps the public repository commit history in sync with that of the private repository.
 name: bosdyn_msgs mirroring
 
 on:
@@ -19,9 +20,9 @@ jobs:
         uses: actions/checkout@v3
         with:
           submodules: true
-          persist-credentials: false
-          fetch-depth: 0
-          fetch-tags: true
+          persist-credentials: false  # to avoid CI credentials from overriding the PAT in secrets
+          fetch-depth: 0  # to bring the entire repository history on checkout
+          fetch-tags: true  # to bring tags on checkout, not only branches
       - name: Push to mirror repository
         run: |
           git push --tags --follow-tags --recurse-submodules=on-demand \