feat: removed dependency on separate PAT

Additionally moved the PR creation to its own job

docs: added comments to all of the workflows

style: formatting updates

.github/workflows/build-base.yml

@@ -3,52 +3,66 @@ name: Reusable zig build workflow
 on:
   workflow_call:
     inputs:
-      # The version to build on
       zig-version:
         required: false
         type: string
         default: 0.13.0
-      # Whether or not to clone submodules
+        description: Version of zig to build with
       get-submodules:
         required: false
         type: string
         default: false
-      # If using sparse checkout, the file patterns to include when cloning
+        description: Whether or not to clone submodules
       sparse-checkout-patterns:
         required: false
         type: string
         default: ""
-      # If building a subproject only, you can specify a working directory
-      # which is the path to that subproject.
+        description: |
+          List of file patterns (globs) to include in the sparse checkout. 
+          If empty, sparse checkout is not used.
       working-directory:
         required: false
         type: string
         default: "."
-      # Whether or not to use a provided package command.
+        description: |
+          If building a sub-project only, you can specify a working directory
+          which is the path to that sub-project.
       is-packaged:
         required: false
         type: boolean
         default: false
+        description: |
+          Whether or not to use a provided package command. This is specifically
+          to output the boxzer output.
       # The github artifact name for uploading build artifacts to
       # If it is blank, nothing will be uploaded
       github-artifact-name:
         required: false
         type: string
         default: ""
+        description: |
+          The name to use for the github actifact that will be uploaded.
       # The path that we should upload artifacts from
       artifact-output-paths:
         required: false
         type: string
         default: ""
+        description: |
+          The path to the generated artifact that will be included within
+          the github artifact upload.
       ref:
         required: false
         type: string
         default: ""
+        description: A sepcific ref to build for (i.e. a version or commit)
     secrets:
       # The downloads url for the packaging step. This is used in boxzer to
       # fill in the manifest downloads location
       downloads-url:
         required: false
+        description: |
+          The download url that will be included in the boxzer manifest output. 
+          If the "is-packaged" option is false, this will not be used.
 
 jobs:
   build-zig:
@@ -57,19 +71,22 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
     steps:
+      # If we just want to use the current commit, simply run a checkout
       - name: Checkout
         if: ${{ inputs.ref == '' }}
         uses: actions/checkout@v4
         with:
           sparse-checkout: ${{ inputs.sparse-checkout-patterns }}
           submodules: ${{ inputs.get-submodules }}
+      # If there is a specific ref we want, check that ref out.
       - name: Checkout Specific Ref
         if: ${{ inputs.ref != '' }}
         uses: actions/checkout@v4
         with:
           ref: ${{ inputs.ref }}
           sparse-checkout: ${{ inputs.sparse-checkout-patterns }}
           submodules: ${{ inputs.get-submodules }}
+      # Setup zig, we use mlugg's setup because it has caching
       - name: Setup Zig
         uses: mlugg/setup-zig@v1
         with:
@@ -80,17 +97,27 @@ jobs:
       - name: Package
         if: ${{ inputs.is-packaged && runner.os == 'macOS' }}
         run: zig build package -- "${{ secrets.downloads-url }}"
+      # We use whether or not an artifact output path is provided and whether
+      # or not there is actually anything in that directory to know whether or
+      # not there is anything to upload.
       - name: Get Should Upload bash
         id: should-upload
         shell: bash
         run: |
-          if [[ ! -z "${{ inputs.artifact-output-paths }}" ]] && test -n "$(find . -maxdepth 1 -name '${{ inputs.artifact-output-paths }}' -print -quit)"; then
+          if [[ ! -z "${{ inputs.artifact-output-paths }}" ]] \
+                && test -n "$(find . -maxdepth 1 \
+                                -name '${{ inputs.artifact-output-paths }}' \
+                                -print -quit)"; then
             echo "SHOULD_UPLOAD=true" >> $GITHUB_OUTPUT; 
           else
             echo "SHOULD_UPLOAD=false" >> $GITHUB_OUTPUT; 
           fi
+      # Upload artifacts if there is something to upload and if there is a
+      # name to upload it to
       - name: Upload Artifacts
-        if: ${{ steps.should-upload.outputs.SHOULD_UPLOAD == 'true' && inputs.github-artifact-name != '' }}
+        if: |
+          steps.should-upload.outputs.SHOULD_UPLOAD == 'true' 
+            && inputs.github-artifact-name != ''
         uses: actions/upload-artifact@v4
         with:
           name: ${{ inputs.github-artifact-name }}

.github/workflows/build-microzig.yml

@@ -21,7 +21,11 @@ on:
 
 jobs:
   build-microzig:
-    if: ${{ ( github.event_name == 'pull_request' && github.base_ref == 'main' ) || github.ref_name == 'main' }}
+    if: |
+      ${{ 
+        ( github.event_name == 'pull_request' && github.base_ref == 'main' ) 
+        || github.ref_name == 'main' 
+      }}
     name: Build
     uses: ./.github/workflows/build-base.yml
     with:
@@ -30,6 +34,15 @@ jobs:
       is-packaged: true
     secrets:
       downloads-url: ${{ secrets.DOWNLOADS_URL }}
+  # If this is a push to main we want to create an automatic test against the
+  # zig-master branch. To do this, we need to create a PR and while we could
+  # just go directly from main to zig-master, this would mean that if the tests
+  # with zig-master fail, the main branch will also display the failure (this
+  # is because github action results are saved based on the commit). To solve
+  # that issue, we create a new branch with a new commit in it, then create
+  # the PR based on that.
+  #
+  # Creates the branch that we will use for the PR to zig-master
   create-branch:
     if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
     name: Create Patch Branch
@@ -42,19 +55,25 @@ jobs:
       contents: write
       pull-requests: write
     steps:
+      # First we checkout the repository
       - uses: actions/checkout@v4
+      # Check if the branch exsits. This will be used in future steps to
+      # conditionally execute them.
       - id: cbe
         name: Check branch exists
         # The list remote returns nothing if the branch does not exist.
         # So, if there is nothing in the command output, it does not exist
         run: |
-          if [[ -z "$(git ls-remote --heads origin master-patch/${{ github.sha }})" ]]; then
+          if [[ -z "$(git ls-remote \
+                        --heads origin master-patch/${{ github.sha }})" ]]; then
             echo "exists=false" >> "$GITHUB_OUTPUT"
           else
             echo "exists=true" >> "$GITHUB_OUTPUT"
           fi
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # If the branch doesn't already exist, we create a new one. We use the
+      # username and email of the last commit.
       - name: Create Branch
         if: steps.cbe.outputs.exists == 'false'
         run: |
@@ -64,37 +83,62 @@ jobs:
           git push -u origin "master-patch/${{ github.sha }}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # Checkout to the new branch
       - name: checkout
         uses: actions/checkout@v4
         with:
           ref: master-patch/${{ github.sha }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # Create an empty commit that will be used to save the ci results
+      # against (For more details see "create-branch" comment)
       - name: add-commit
         run: |
           git config user.name "$(git log -1 --pretty=format:'%an')"
           git config user.email "$(git log -1 --pretty=format:'%ae')"
-          git commit --author "ZEG Github Action <>" -m "chore: commit for zig master build ci" --allow-empty
+          git commit \
+            --author "ZEG Github Action <>" \
+            -m "chore: commit for zig master build ci" \
+            --allow-empty
           git push
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  # Now that a branch exists, we can create our PR. To do this we will use the
+  # github command line tool.
+  create-pr:
+    if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
+    name: Create Pull Request
+    runs-on: ubuntu-latest
+    needs: create-branch
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      # Check if the PR already exists, this will be used to conditionally
+      # create the PR.
       - id: cpe
         name: check pr exists
         # github actions pr only outputs when the query find something.
         # So, if the output is empty, pr does not exist
         run: |
-          gh pr list -B zig-master -H "master-patch/${{ github.sha }}" 2> check-pr-exists-output
-          if [[ -z "$(cat check-pr-exists-output)" ]]; then 
+          gh pr list -B zig-master \
+            -H "${{ needs.create-branch.outputs.branch }}" 2> check-exists-out
+          if [[ -z "$(cat check-exists-out)" ]]; then 
             echo "exists=false" >> "$GITHUB_OUTPUT"
           else
             echo "exists=true" >> "$GITHUB_OUTPUT"
           fi
-          rm check-pr-exists-output
+          cat check-exists-out
+          rm check-exists-out
         env:
-          GITHUB_TOKEN: ${{ secrets.PR_CREATE_PAT }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # Create the actual PR if it doesn't already exist
       - name: create pull request,
         if: steps.cpe.outputs.exists == 'false'
         run: |
-          gh pr create -B zig-master -H master-patch/${{ github.sha }} --title 'Testing commit ${{ github.sha }} with zig master' --body 'Created by Github action'
+          gh pr create -B zig-master -H master-patch/${{ github.sha }} \
+            --title 'Testing commit ${{ github.sha }} with zig master' \
+            --body 'Created by Github action'
         env:
-          GITHUB_TOKEN: ${{ secrets.PR_CREATE_PAT }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-base.yml

@@ -6,62 +6,87 @@ permissions:
 on:
   workflow_call:
     inputs:
-      # The tag that we are publishing to
       tag:
         required: false
         type: string
         default: ""
-      # The name that will be used to download artifact from github
+        description: The version tag to publish
       github-artifact-name:
         required: true
         type: string
-      # The name of what we are publishing
+        description: The github artifact to download the artifact from.
       artifact-name:
         required: true
         type: string
+        description: The name of what we are publishing
       # The path after the target-path to publish the artifact to
       # {artifact | {target-path}/{target-artifact-path}
       target-artifact-path:
         required: false
         type: string
         default: ""
+        description: |
+          The path that goes after target-path to specify a subdirectory
+          to publish to. Final path: {target-path}/{target-artifact-path}
       # The path within the github artifact that the artifact is located at.
       source-path:
-        required: true
+        required: false
         type: string
+        default: ""
+        description: |
+          The path within the github artifact where the artifact is located at
     secrets:
       # The target path within the host share to save files to
       target-path:
         required: true
+        description: |
+          The path within the host machine where the data should be published
+          to.
       ssh-key:
         required: true
+        description: The ssh private key that is used to publish to the host.
       host:
         required: true
+        description: The host that has sshd running to publish to.
       port:
         required: true
+        description: The port the host is running sshd on.
       user:
         required: true
+        description: THe username to log in to the server as.
 
 jobs:
   publish:
     runs-on: macos-latest
     steps:
+      # If this is somehow not run from a tag, fail. This is a remainder from
+      # when the build side and publish side were done in one workflow.
       - name: Check tag status
-        if: ${{ startsWith(github.ref, 'refs/tags/') && ! endsWith(github.ref, inputs.tag) }}
+        if: |
+          ${{ startsWith(github.ref, 'refs/tags/') 
+              && ! endsWith(github.ref, inputs.tag) }}
         uses: actions/github-script@v3
         with:
           script: |
             core.setFailed("Provided tag does not match github ref tag")
+      # Download the requested github artifact
       - name: Download artifacts
         id: download
         uses: actions/download-artifact@v4
         with:
           name: ${{ inputs.github-artifact-name }}
+      # Get the path to where the artifact is at. This is the path to the
+      # downloaded artifact that is relative to the github workspace with the
+      # source-path parameter tacked on the end.
       - name: Get Source Path
         shell: bash
         id: get-source-path
         run: |
-          echo "path=$(realpath -s --relative-to="${{ github.workspace }}" "${{ steps.download.outputs.download-path }}/${{ inputs.source-path }}")" >> $GITHUB_OUTPUT
+          echo "path=$( \
+            realpath -s --relative-to="${{ github.workspace }}" \
+            "${{ steps.download.outputs.download-path }}/${{ inputs.source-path }}" \
+            )" >> $GITHUB_OUTPUT
+      # Publish to the host
       - name: Publish Release
         uses: easingthemes/ssh-deploy@main
         with:
@@ -72,6 +97,11 @@ jobs:
           REMOTE_USER: ${{ secrets.user }}
           REMOTE_PORT: ${{ secrets.port }}
           TARGET: ${{ secrets.target-path }}/${{ inputs.target-artifact-path }}
+      # (Not working as intented) Un-needed for now. This step would go through
+      # every binary and folder within the source path and add it to the release
+      # if it were a file, or compress it and then add the compressed file to
+      # the release.
+      # Issue: Adds things that are not desired in the output.
       #- name: Handle Folder Release Artifact
       #  if: ${{ startsWith(github.ref, 'refs/tags/') && endsWith(github.ref, inputs.tag) }}
       #  shell: bash
@@ -92,6 +122,7 @@ jobs:
       #        mv "$i" "artifacts-${{ github.sha }}"
       #      fi
       #    done
+      # Create the release draft on GitHub.
       - name: Create Release Draft
         if: ${{ startsWith(github.ref, 'refs/tags/') && endsWith(github.ref, inputs.tag) }}
         uses: ncipollo/release-action@v1

.github/workflows/publish-microzig.yml

@@ -10,6 +10,7 @@ on:
       - "v*.*.*-*"
 
 jobs:
+  # Build the project to ensure it works. Also to get the binaries.
   build-microzig:
     uses: ./.github/workflows/build-base.yml
     with:
@@ -20,6 +21,7 @@ jobs:
       artifact-output-paths: boxzer-out
     secrets:
       downloads-url: ${{ secrets.DOWNLOADS_URL }}
+  # Publish microzig
   publish-microzig:
     uses: ./.github/workflows/publish-base.yml
     needs: build-microzig

.github/workflows/zig-master-build.yml

@@ -5,6 +5,7 @@ on:
   pull_request:
     branches: [zig-master]
 
+# A simple workflow that will, upon a push or PR to zig-master, build microzig
 jobs:
   # No we don't need this still, I'm just happy about figuring out the jq query
   # (I don't want to hear that it is simple, I think it's cool xD)