ci: document ci

.github/labeler.yml

@@ -1,16 +1,30 @@
+# Release branches where trunk branches are merge-committed to trigger releases
+
 release:
 - base-branch:
   - 'release/.+'
-  - 'maintenance/.+/[0-9]+\.([0-9]+|x)\.x'
+  - 'maintenance/.+/release/[0-9]+\.([0-9]+|x)\.x'
+
+# Trunk branches where changes are collected before assets are released
 
 trunk:
 - base-branch:
   - 'main'
   - 'maintenance/.+/trunk/[0-9]+\.([0-9]+|x)\.x'
 
+# Label any maintenance branch, trunk and release
+
 maintenance:
 - base-branch:
-  - 'maintenance/.+/.+'
+  - 'maintenance/.+/.+/[0-9]+\.([0-9]+|x)\.x'
+
+# Label PRs into the main branch
+
+main:
+- base-branch:
+  - 'main'
+
+# Labels for PRs on asset specific branches
 
 controller-container:
 - base-branch:

.github/workflows/controller-container.yaml

@@ -2,18 +2,26 @@ name: Controller Container
 
 on:
   pull_request:
+    # Ignore PRs on branches specifically intended for other assets
     branches-ignore:
       - '*/fizzbuzz-chart*'
       - '*/fizzbuzz-crds-chart*'
+    # Only consider PRs that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/flake8.yaml'
       - '.github/workflows/controller-container.yaml'
       - 'containers/controller/**'
+    # Make sure all workflows that are "required checks" for a given
+    # branch protection rule have the same paths: and branches-ignore:
+    # filters. Otherwise, you can end up in a deadlock waiting on a
+    # required check that will never be executed.
   push:
+    # Only release off of release and maintenance branches for this asset
     branches:
-      - 'maintenance/controller-container/[0-9]+.x.x'
-      - 'maintenance/controller-container/[0-9]+.[0-9]+.x'
+      - 'maintenance/controller-container/release/[0-9]+.x.x'
+      - 'maintenance/controller-container/release/[0-9]+.[0-9]+.x'
       - 'release/controller-container'
+    # Only consider pushes that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/controller-container.yaml'
       - 'containers/controller/**'
@@ -25,10 +33,11 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
+  # Needed to generate releases safely
   cancel-in-progress: false
 
 jobs:
-  controller-container:
+  build:
     uses: SwanseaUniversityMedical/workflows/.github/workflows/pr-and-release-container.yaml@feat/build-cache
     with:
       job-name: controller-container
@@ -38,8 +47,7 @@ jobs:
       release-tag-format: 'controller-container-${version}'
       release-branches: |
         [
-          'maintenance/controller-container/[0-9]+\.x\.x',
-          'maintenance/controller-container/[0-9]+\.[0-9]+\.x',
+          'maintenance/controller-container/[0-9]+\.([0-9]+|x)\.x',
           'release/controller-container'
         ]
       cosign-public-key: ${{ vars.COSIGN_PUBLIC_KEY }}

.github/workflows/fizzbuzz-chart.yaml

@@ -2,17 +2,25 @@ name: Fizzbuzz Chart
 
 on:
   pull_request:
+    # Ignore PRs on branches specifically intended for other assets
     branches-ignore:
       - '*/controller-container*'
       - '*/fizzbuzz-crds-chart*'
+    # Only consider PRs that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/fizzbuzz-chart.yaml'
       - 'charts/fizzbuzz/**'
+    # Make sure all workflows that are "required checks" for a given
+    # branch protection rule have the same paths: and branches-ignore:
+    # filters. Otherwise, you can end up in a deadlock waiting on a
+    # required check that will never be executed.
   push:
+    # Only release off of release and maintenance branches for this asset
     branches:
       - 'maintenance/fizzbuzz-chart/[0-9]+.x.x'
       - 'maintenance/fizzbuzz-chart/[0-9]+.[0-9]+.x'
       - 'release/fizzbuzz-chart'
+    # Only consider pushes that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/fizzbuzz-chart.yaml'
       - 'charts/fizzbuzz/**'
@@ -24,10 +32,11 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
+  # Needed to generate releases safely
   cancel-in-progress: false
 
 jobs:
-  fizzbuzz-chart:
+  build:
     uses: SwanseaUniversityMedical/workflows/.github/workflows/[email protected]
     with:
       job-name: fizzbuzz-chart
@@ -38,8 +47,7 @@ jobs:
       release-tag-format: 'fizzbuzz-chart-${version}'
       release-branches: |
         [
-          'maintenance/fizzbuzz-chart/[0-9]+\.x\.x',
-          'maintenance/fizzbuzz-chart/[0-9]+\.[0-9]+\.x',
+          'maintenance/fizzbuzz-chart/[0-9]+\.([0-9]+|x)\.x',
           'release/fizzbuzz-chart'
         ]
       cosign-public-key: ${{ vars.COSIGN_PUBLIC_KEY }}

.github/workflows/fizzbuzz-crds-chart.yaml

@@ -2,18 +2,25 @@ name: Fizzbuzz CRDs Chart
 
 on:
   pull_request:
+    # Ignore PRs on branches specifically intended for other assets
     branches-ignore:
       - '*/controller-container*'
       - '*/fizzbuzz-chart*'
+    # Only consider PRs that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/fizzbuzz-crds-chart.yaml'
       - 'charts/fizzbuzz-crds/**'
-
+    # Make sure all workflows that are "required checks" for a given
+    # branch protection rule have the same paths: and branches-ignore:
+    # filters. Otherwise, you can end up in a deadlock waiting on a
+    # required check that will never be executed.
   push:
+    # Only release off of release and maintenance branches for this asset
     branches:
       - 'maintenance/fizzbuzz-crds-chart/[0-9]+.x.x'
       - 'maintenance/fizzbuzz-crds-chart/[0-9]+.[0-9]+.x'
       - 'release/fizzbuzz-crds-chart'
+    # Only consider pushes that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/fizzbuzz-crds-chart.yaml'
       - 'charts/fizzbuzz-crds/**'
@@ -25,10 +32,11 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
+  # Needed to generate releases safely
   cancel-in-progress: false
 
 jobs:
-  fizzbuzz-crds-chart:
+  build:
     uses: SwanseaUniversityMedical/workflows/.github/workflows/[email protected]
     with:
       job-name: fizzbuzz-crds-chart
@@ -39,8 +47,7 @@ jobs:
       release-tag-format: 'fizzbuzz-crds-chart-${version}'
       release-branches: |
         [
-          'maintenance/fizzbuzz-crds-chart/[0-9]+\.x\.x',
-          'maintenance/fizzbuzz-crds-chart/[0-9]+\.[0-9]+\.x',
+          'maintenance/fizzbuzz-crds-chart/release/[0-9]+\.([0-9]+|x)\.x',
           'release/fizzbuzz-crds-chart'
         ]
       cosign-public-key: ${{ vars.COSIGN_PUBLIC_KEY }}

.github/workflows/flake8.yaml

@@ -2,20 +2,27 @@ name: Flake8
 
 on:
   pull_request:
+    # Ignore PRs on branches specifically intended for other assets
     branches-ignore:
       - '*/fizzbuzz-chart*'
       - '*/fizzbuzz-crds-chart*'
+    # Only consider PRs that change files for this asset, including ci scripts
     paths:
       - '.github/workflows/flake8.yaml'
       - '.github/workflows/controller-container.yaml'
       - 'containers/controller/**'
+    # Make sure all workflows that are "required checks" for a given
+    # branch protection rule have the same paths: and branches-ignore:
+    # filters. Otherwise, you can end up in a deadlock waiting on a
+    # required check that will never be executed.
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
+  # This linting can be cancelled if there is a newer commit to lint
   cancel-in-progress: true
 
 jobs:
-  flake8:
+  lint:
     runs-on:
       labels: [self-hosted, linux, x64]
       group: light

.github/workflows/labeler.yaml

@@ -7,7 +7,7 @@ on:
       - reopened
 
 jobs:
-  label:
+  labeler:
     runs-on: ubuntu-latest
     permissions:
       contents: read