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

.github/workflows/build.yml

@@ -1,26 +1,45 @@
 name: build-ublue
 on:
-  pull_request:
+  # Build *every* branch at 10:20pm UTC every day (1 hr delay after "nvidia" builds),
+  # regardless of the branch names. (Not just "live, template and main" branches.)
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+  schedule:
+    - 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"
-  schedule:
-    - cron: "20 22 * * *" # 10:20pm everyday (1 hr delay after 'nvidia' builds)
-  push:
-    branches:
-      - main
+  # 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:
   IMAGE_REGISTRY: ghcr.io/${{ github.repository_owner }}
 
 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,18 +165,18 @@ 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 }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       # Sign container
       - uses: sigstore/[email protected]
-        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) }}"

README.md

@@ -15,6 +15,9 @@ Don't worry, it only requires some basic knowledge about using the terminal and
 > **Note**
 > Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used [`create-ublue-image`](https://github.com/EinoHR/create-ublue-image), in which case the previous repo identifier should already be your repo's details.
 
+> **Warning**
+> To start, you *must* create a branch called `live` which is exclusively for your customizations. That is the **only** branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your `live` branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits".
+
 ## Customization
 
 The easiest way to start customizing is by looking at and modifying `recipe.yml`. It's documented using comments and should be pretty easy to understand.