ci(release): refine documentation and add version pinning

Author: Aaron-Ritter

.github/workflows/release.yaml

@@ -6,28 +6,38 @@ on:
     branches:
       - main
 
+# The different jobs of this workflow need the following permissions
 permissions:
+  # The release-please-action requires these permissions to create a github release
   contents: write
+  # The release-please-action requires these permissions to create and modify pull requests
   pull-requests: write
+  # The release-please-action requires these permissions to read pull request labels
   repository-projects: read
-  # only required for workflows in private repositories
+  # This workflow calls and imports multiple other workflows and actions. T
+  # It is only required for workflows in private repositories
   actions: write
+  # The release workflow calls multiple code quality and security workflows which create security output
   security-events: write
-  # required to fetch internal or private CodeQL packs
+  # This is required to fetch internal or private CodeQL packs
   packages: read
 
+# This workflow is part of the release group and will not run concurrently with other workflows in the same group
 concurrency:
   group: release
 
 jobs:
   # This job creates the necessary labels for the release-please PRs:
+  # GitHub introduced a situation where these labels are not created which caused the release-please-action to fail.
+  # googleapis underlying release-please needs to add a check for the existence of these labels,
+  # and create them if they are not present.
   # https://github.com/googleapis/release-please-action/issues/1074
   label-check:
     name: Create release-please PR labels
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v4.2.2
 
       - name: Add labels to the repository if not present
         env:
@@ -70,7 +80,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: [ label-check, initial-e2e-test, mobsf, swiftlint, codeql-package, codeql-samples-quickstart ]
     outputs:
+      # This output is used to determine if a release was created
       releases_created: ${{ steps.release.outputs.releases_created }}
+      # This output is used to determine the tag name of the release
       tag_name: ${{ steps.release.outputs.tag_name }}
     steps:
       - id: release
@@ -84,8 +96,9 @@ jobs:
   prerelease-test:
     name: Run Prerelease Tests
     runs-on: ubuntu-latest
-    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     needs: [ prerelease-prep ]
+    # This job runs only if there was no release created
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     steps:
       - name: End To End Test
         run: |
@@ -94,23 +107,26 @@ jobs:
   # This job runs the E2E tests with FusionAuth Matrix as a prerequisite for creating the prerelease
   prerelease-e2e-test-fusionauth-matrix:
     name: Run Prerelease E2E Tests with FusionAuth Matrix
-    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     needs: [ prerelease-prep ]
+    # This job runs only if there was no release created
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     uses: ./.github/workflows/e2e-test-fusionauth-matrix-ios-latest.yml
 
   # This job runs the E2E tests with iOS Matrix as a prerequisite for creating the prerelease
   prerelease-e2e-test-ios-matrix:
     name: Run Prerelease E2E Tests with iOS Matrix
-    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     needs: [ prerelease-prep ]
+    # This job runs only if there was no release created
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'false' }}
     uses: ./.github/workflows/e2e-test-fusionauth-latest-ios-matrix.yml
 
   # This job runs creates the Prerelease and creates a subsequent Release Pull Request
   prerelease:
     name: Create Prerelease and Release Pull Request
     runs-on: ubuntu-latest
-    if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     needs: [ prerelease-prep, prerelease-e2e-test-fusionauth-matrix, prerelease-e2e-test-ios-matrix ]
+    # This job runs only if a release was created and the tag name contains 'rc'
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     steps:
       - name: Pre Release Step
         run: |
@@ -127,6 +143,7 @@ jobs:
     name: Post Prerelease Steps
     runs-on: ubuntu-latest
     needs: [ prerelease ]
+    # This job runs only if a release was created and the tag name contains 'rc'
     if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     steps:
       - name: Post Prerelease Step
@@ -137,8 +154,9 @@ jobs:
   release:
     name: Create Release
     runs-on: ubuntu-latest
-    if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && !contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     needs: [ prerelease-prep ]
+    # This job runs only if a release was created and the tag name does not contain 'rc'
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && !contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     steps:
       - name: Release Step
         run: |
@@ -168,6 +186,8 @@ jobs:
     name: Post Release Steps
     runs-on: ubuntu-latest
     needs: [ release ]
+    # This job runs only if a release was created and the tag name does not contain 'rc'
+    if: ${{ needs.prerelease-prep.outputs.releases_created == 'true' && !contains(needs.prerelease-prep.outputs.tag_name, 'rc') }}
     steps:
       - name: Post Release Step
         run: |