feat!: only deploy the branch named "live", to simplify development

- Documents all triggers, since this repository is a starting point for people to learn from.

- Only deploys the branch named "live", which gives people more deliberate control of what gets deployed. Why not name it "main"? Because that complicates things a lot when forking this template to your own repos, since the template's default branch is also (currently) named "main", which would among other things complicate the act of syncing the fork via GitHub's web UI. The name "main" also confuses the user since it doesn't give them any hint that it's the only live-published branch.

- Only automatically builds the branches "live", "template" or "main" when pushing new commits. But builds any branch name when it's a pull request, to allow automated PR "build checks" to succeed.

.github/workflows/build.yml

@@ -1,19 +1,36 @@
 name: build-ublue
 on:
-  pull_request:
+  # Build *every* branch at 10:20pm UTC every day (1 hr delay after "nvidia" builds),
-    branches:
+  # regardless of the branch names. (Not just "live, template and main" branches.)
-      - main
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
-    paths-ignore:
-      - "**.md"
-      - "**.txt"
   schedule:
-    - cron: "20 22 * * *" # 10:20pm everyday (1 hr delay after 'nvidia' builds)
+    - cron: "20 22 * * *"
+  # Build automatically after pushing commits or tags to the "live", "template"
+  # or "main" branches, except when the commit only affects "documentation" text files.
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push
   push:
     branches:
+      - live
+      - template
       - main
     paths-ignore:
       - "**.md"
       - "**.txt"
+  # Build pull requests whenever they are opened or updated, to make sure they
+  # work. The build won't be deployed, since we filter out PRs in the deployment
+  # stage. Note that submitted PRs run the workflow of the *fork's* own primary
+  # branch, using the fork's own secrets/environment. Please be sure to sync
+  # your primary branch with upstream's latest workflow before submitting PRs!
+  # For pull requests, we build *any* branch regardless of name, to allow "build
+  # checks" to succeed for typical PR branch names such as "fix-something".
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+  pull_request:
+    paths-ignore:
+      - "**.md"
+      - "**.txt"
+  # Build when manually triggering this workflow for a branch. This allows you
+  # to build any branch, even if it's not listed in the automated triggers above.
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
   workflow_dispatch:
 
 env:
@@ -21,6 +38,8 @@ env:
 
 jobs:
   push-ghcr:
+    # Only deploys the branch named "live". Ignores all other branches, to allow
+    # having "development" branches without interfering with GHCR image uploads.
     name: Build and push image
     runs-on: ubuntu-22.04
     permissions:
@@ -131,7 +150,7 @@ jobs:
       - name: Push To GHCR
         uses: redhat-actions/push-to-registry@v2
         id: push
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/live'
         env:
           REGISTRY_USER: ${{ github.actor }}
           REGISTRY_PASSWORD: ${{ github.token }}
@@ -146,7 +165,7 @@ jobs:
 
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v2
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/live'
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -154,10 +173,10 @@ jobs:
 
       # Sign container
       - uses: sigstore/cosign-installer@v3.0.3
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/live'
 
       - name: Sign container image
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/live'
         run: |
           cosign sign -y --key env://COSIGN_PRIVATE_KEY ${{ steps.registry_case.outputs.lowercase }}/${{ env.IMAGE_NAME }}@${TAGS}
         env:
@@ -166,6 +185,6 @@ jobs:
           COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
 
       - name: Echo outputs
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/live'
         run: |
           echo "${{ toJSON(steps.push.outputs) }}"