Updating Documentation

.github/workflows/update-nudge-version.yml

@@ -120,4 +120,3 @@ jobs:
           body: "A new version of macOS has been released, please review the changes and merge this PR to update the Nudge osVersionRequirements key"
           add-paths: |
             ${{ inputs.unos_nudge_json_file }}
-          # token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -2,7 +2,7 @@
 
 Reusable Workflow and stand-alone Python script for updating a Nudge osVersionRequirements array using Apple's gdfm service (https://gdmf.apple.com/v2/pmv).
 
-## Reusable Workflow (in progress)
+## Reusable Workflow
 
 To call this workflow from your own repo, create a GitHub Actions Workflow file with the following `jobs` block:
 
@@ -11,6 +11,8 @@ name: "Test workflow_call"
 
 on:
   workflow_dispatch:
+  # schedule: # Uncomment to run this on a schedule
+  #   - cron: '0 1 * * *' # Runs at 01:00am each day UTC
 
 permissions:
   contents: write
@@ -30,47 +32,8 @@ jobs:
 
 ## Python Script
 
-This has been written and tested on Python 3.11. The script can be run independtly of the GitHub Action and takes the following input:
-
-- `--debug` OR `-d` OR `UNOS_DEBUG` (environment variable)
-  - Produces verbose output to the console
-- `--test-mode` OR `-t` OR `UNOS_TEST_MODE` (environment variable)
-  - Will enable verbose logging and prevent writing anything to disk
-- `--version` OR `-v` OR `UNOS_MIN_MAJOR_OS_VERSION` (environment variable)
-  - Sets the minimum major OS version supported in your environment
-- `--file` OR `-f` OR `UNOS_NUDGE_JSON_FILE` (environment variable)
-  - Location of your json file containing the `osVersionRequirements` array. If none is specified the file `nudge.json` is written to the current working directory.
-
-## Running the standalone script
-
-``` shell
-# Clone Repo
-gh repo clone smithjw/nudge-actions
-cd nudge-actions
-
-# Create Python Virtual Environment
-python -m venv .venv
-source .venv/bin/activate
-
-# Install Requirements
-pip install -r app/requirements.txt
-
-# Run Script
-python app/update_nudge_osVersionRequirements.py --test-mode
-```
+To run the Python script independly of the GitHub Actions Reusable Workflow, [please see the documentation here](app/README.md)
 
 ### Notes
 
 If https://gdmf.apple.com/v2/pmv changes format in the future or can no longer be used, an alternative could be https://jamf-patch.jamfcloud.com/v1/software/
-
-### Updating Requirements Hashes
-
-> *This is really a note for FutureJames*
-
-To ensure that the hashes supplied in `requirements.txt` work across multiple platforms, we're taking advantakge of the Python package [`pip-compile-cross-platform`](https://pypi.org/project/pip-compile-cross-platform/) which can be installed with the command:
-
-`pip install --user pip-compile-cross-platform`
-
-To run, execute the following command:
-
-`pip-compile-cross-platform --min-python-version 3.11 app/requirements.in`

app/README.md

@@ -0,0 +1,42 @@
+# update_nudge_osVersionRequirements.py
+
+This has been written and tested on Python 3.11. The script can be run independtly of the GitHub Action and takes the following inputs:
+
+- `--debug` OR `-d` OR `UNOS_DEBUG` (environment variable)
+  - Produces verbose output to the console
+- `--test-mode` OR `-t` OR `UNOS_TEST_MODE` (environment variable)
+  - Will enable verbose logging and prevent writing anything to disk
+- `--version` OR `-v` OR `UNOS_MIN_MAJOR_OS_VERSION` (environment variable)
+  - Sets the minimum major OS version supported in your environment
+- `--file` OR `-f` OR `UNOS_NUDGE_JSON_FILE` (environment variable)
+  - Location of your json file containing the `osVersionRequirements` array. If none is specified the file `nudge.json` is written to the current working directory.
+
+## Running the standalone script
+
+``` shell
+# Clone Repo
+gh repo clone smithjw/nudge-actions
+cd nudge-actions/app
+
+# Create Python Virtual Environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install Requirements
+pip install -r requirements.txt
+
+# Run Script
+python update_nudge_osVersionRequirements.py --test-mode
+```
+
+## Updating Requirements Hashes
+
+> *This is really a note for FutureJames*
+
+To ensure that the hashes supplied in `requirements.txt` work across multiple platforms, we're taking advantakge of the Python package [`pip-compile-cross-platform`](https://pypi.org/project/pip-compile-cross-platform/) which can be installed with the command:
+
+`pip install --user pip-compile-cross-platform`
+
+To run, execute the following command:
+
+`pip-compile-cross-platform --min-python-version 3.11 app/requirements.in`

examples/README.md

@@ -0,0 +1,5 @@
+# Example Actions
+
+Once you've setup the GitHub Action calling [`update-nudge-version.yml`](/.github/workflows/update-nudge-version.yml) to keep your json file up-to-date, you'll need to either add some additonal steps into that Workflow for uploading it a webserver that your Mac fleet can reach, or create a separate Workflow entirelty.
+
+In this folder I'll have a few examples of how you can upload that file when updated.

examples/upload_to_azure.yml

@@ -0,0 +1,39 @@
+name: Upload json File to Azure
+# This example is taken from the Azure Documentation and a direct link is below
+# https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-static-site-github-actions?tabs=userlevel#add-your-workflow
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'nudge.json'
+      # Modify the name of this to match what your json file is called
+
+jobs:
+  upload-file:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: azure/login@v1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+
+      - name: Upload to blob storage
+        uses: azure/CLI@v1
+        with:
+          inlineScript: |
+            az storage blob upload-batch --account-name <STORAGE_ACCOUNT_NAME> --auth-mode key -d '$web' -s 'nudge.json'
+            # Modify the name of the json file to match what your json file is called
+
+      # If you're using a CDN, you can purge the cache with the following step
+      - name: Purge CDN endpoint
+        uses: azure/CLI@v1
+        with:
+          inlineScript: |
+            az cdn endpoint purge --content-paths  "/*" --profile-name "CDN_PROFILE_NAME" --name "CDN_ENDPOINT" --resource-group "RESOURCE_GROUP"
+
+      - name: logout
+        run: |
+          az logout
+        if: always()