Merge pull request #115 from puppetlabs/maint_update_docs

Update workflow restarter documentation

Author: danadoherty639

docs/workflow-restarter.md

@@ -12,47 +12,13 @@ If setting up the the `workflow-restarter` for the first time, then make sure to
 
 ### Initialize the `Workflow Restarter`
 
-First, configure the `workflow-restarter-proxy` custom action by creating a `workflow-restarter.yml` file beneath the `.github/workflows` directory in your repository.
+In order to begin using the workflow-restarter, you need to first raise a PR and add the workflow restarter to your target repository.  In other words,
 
-Second, configure the `workflow-restarter` re-usable workflow:
+* Copy [workflow-restarter.yml](./workflow-restarter/workflow-restarter.yml) and [workflow-restarter-test.yml](./workflow-restarter/workflow-restarter-test.yml) to the `.github/workflows` directory of your target directory.
+* Raise and merge a PR adding the above to the main branch of your repository.
+* Verify that the `Workflow Restarter TEST` workflow works as expected.  See the [Appendix](#verify-workflow-restarter-with-workflow-restarter-test) for more information on what you should expect to see.
 
-```yaml
-name: Workflow Restarter
-on:
-  workflow_dispatch:
-    inputs:
-      repo:
-        description: "GitHub repository name."
-        required: true
-        type: string
-      run_id:
-        description: "The ID of the workflow run to rerun."
-        required: true
-        type: string
-      retries:
-        description: "The number of times to retry the workflow run."
-        required: false
-        type: string
-        default: "3"
-
-jobs:
-  call-reusable-workflow:
-    uses: "puppetlabs/cat-github-actions/.github/workflows/workflow-restarter.yml@main"
-    with:
-      repo: ${{ inputs.repo }}
-      run_id: ${{ inputs.run_id }}
-      retries: ${{ inputs.retries }}
-```
-
-Finally, verify that the `workflow-restarter.yml` performs as expected: 
-1. Add a `workflow-restarter-test.yml` file to `.github/workflows`, copy the contents of `./github/workflows/workflow-restarter-test` from this repository
-2. Kick off the `workflow-restarter-test` and it should fail and be re-started 3 times.  For example output see the [appendix below](#verify-workflow-restarter-with-workflow-restarter-test).
-
-### Configure an existing workflow to use `on-failure-workflow-restarter`
-
-Now add something like the following `yaml` job at the end of your workflow, changing only the `needs` section to suit.  
-
-For example, the following will trigger a restart if either the `acceptance` or the `unit` jobs preceeding it fail.  A restart of the failing jobs will be attempted 3 times at which point if the failing jobs continue to fail, then the workflow will be marked as failed.  If, however, at any point the `acceptance` and `unit` both pass fine then the restarted workflow will be marked as successful
+Once the above `Workflow Restarter TEST` is working then you should be able to add the workflow restarter to any of your existing github workflows.  The key is to re-use the `on-failure-workflow-restarter-proxy` located in the `Workflow Restarter TEST`.  For example, the following will trigger a restart if either the `acceptance` or the `unit` jobs preceeding it fail.  A restart of the failing jobs will be attempted 3 times at which point if the failing jobs continue to fail, then the workflow will be marked as failed.  If, however, at any point the `acceptance` and `unit` both pass fine then the restarted workflow will be marked as successful
 
 ```yaml
  on-failure-workflow-restarter-proxy:
@@ -82,22 +48,22 @@ For example, the following will trigger a restart if either the `acceptance` or
 
 The following shows 3 `Workflow Restarter` occuring after the `Workflow Restarter TEST`, which is set to fail continuously.
 
-![alt text](image.png)
+![alt text](./workflow-restarter/image.png)
 
 Looking closer at the `Workflow Restarter TEST` reveals
 
 * that the workflow includes 2 jobs `unit` and `acceptance`; and
 * that the workflow has been re-run 3 times, e.g.,
 
-![alt text](image-1.png)
+![alt text](./workflow-restarter/image-1.png)
 
 Further, the following sequence of screenshots shows that only failed jobs are re-run.
 
 * The `on-failure-workflow-restarter` job **(1)** is triggered by the failure of the `unit` job and **(2)** successfully calls the `workflow-restarter` workflow
 * The `workflow-restarter` in turn triggers a re-run of the `unit` job **(3)** and the `Workflow Restarter TEST` shows this as an incremented attempt count at **(4)**.
 
-![alt text](image-2.png)
+![alt text](./workflow-restarter/image-2.png)
 
-![alt text](image-3.png)
+![alt text](./workflow-restarter/image-3.png)
 
-![alt text](image-4.png)
+![alt text](./workflow-restarter/image-4.png)

docs/image-1.png renamed to docs/workflow-restarter/image-1.png

@@ -0,0 +1,63 @@
+name: Workflow Restarter TEST
+
+on:
+  workflow_dispatch:
+    inputs:
+      fail:
+        description: >
+          For (acceptance, unit) jobs: 
+          'true'  = (fail, succeed) and 
+          'false' = (succeed, fail)  
+        required: true
+        default: 'true'
+env:
+  SOURCE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check outcome
+      run: |
+        if [ "${{ github.event.inputs.fail }}" = "true" ]; then
+          echo "'unit' job succeeded"
+          exit 0
+        else
+          echo "'unit' job failed"
+          exit 1
+        fi
+  acceptance:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check outcome
+      run: |
+        if [ "${{ github.event.inputs.fail }}" = "true" ]; then
+          echo "'acceptance' job failed"
+          exit 1
+        else
+          echo "'acceptance' job succeeded"
+          exit 0
+        fi
+  
+  on-failure-workflow-restarter-proxy:
+    # (1) run this job after the "acceptance" job and...
+    needs: [acceptance, unit]
+    # (2) continue ONLY IF "acceptance" fails
+    if: always() && needs.acceptance.result == 'failure' || needs.unit.result == 'failure'
+    runs-on: ubuntu-latest
+    steps:
+      # (3) checkout this repository in order to "see" the following custom action
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # (4) "use" the custom action to retrigger the failed "acceptance job" above
+      # NOTE: pass the SOURCE_GITHUB_TOKEN to the custom action because (a) it must have
+      # this to trigger the reusable workflow that restarts the failed job; and
+      # (b) custom actions do not have access to the calling workflow's secrets
+      - name: Trigger reusable workflow
+        uses: "puppetlabs/cat-github-actions/.github/actions/workflow-restarter-proxy@main"
+        env:
+          SOURCE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          repository: ${{ github.repository }}
+          run_id: ${{ github.run_id }}

docs/image-2.png renamed to docs/workflow-restarter/image-2.png

@@ -0,0 +1,26 @@
+# target-repo/.github/workflows/call-reusable-workflow.yml
+name: Workflow Restarter
+on:
+  workflow_dispatch:
+    inputs:
+      repo:
+        description: "GitHub repository name."
+        required: true
+        type: string
+      run_id:
+        description: "The ID of the workflow run to rerun."
+        required: true
+        type: string
+      retries:
+        description: "The number of times to retry the workflow run."
+        required: false
+        type: string
+        default: "3"
+
+jobs:
+  call-reusable-workflow:
+    uses: "puppetlabs/cat-github-actions/.github/workflows/workflow-restarter.yml@main"
+    with:
+      repo: ${{ inputs.repo }}
+      run_id: ${{ inputs.run_id }}
+      retries: ${{ inputs.retries }}