Merge pull request #3 from urcomputeringpal/example

Example

.github/workflows/required.yml

@@ -11,19 +11,28 @@ on:
     types:
       - completed
 
+permissions:
+  contents: read
+  actions: read
+  statuses: write
+
+run-name: >
+  Process ${{ github.event.workflow_run.conclusion }} of ${{
+  github.event.workflow_run.name }}
+
 jobs:
   success:
     if:
       contains(fromJSON('["merge_group", "pull_request"]'),
       github.event.workflow_run.event)
-    name: Create appropriate status
+    name: Check required workflow status
     runs-on: ubuntu-latest
     permissions:
       contents: read
       actions: read
       statuses: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ./
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,3 +1,73 @@
-# Required workflows
+# Optional required workflows
 
-Configure required workflows in your repository. Use path filters. Be free.
+Configure required workflows in your repository. Use path filters. Leave your
+GitHub org administrator alone.
+
+Use this Action to configuring required workflows in a workflow file protected
+by `CODEOWNERS` in your repository instead of in your repository settings.
+
+## How it works
+
+- A workflow in your repository is created that calls this Action
+- This workflow contains a list of other workflows that are required to pass
+- When any of those workflows complete on a PR, this workflow will check to see
+  if ANY of them are present on the same SHA
+- If **all** of the matching workflows on the same SHA **have passed**, this
+  workflow will create a success status
+- If **any** of the matching workflows on the same SHA **are missing**, this
+  workflow **will still create a success status**
+  - This allows you to use path filters to skip certain workflows on certain
+    paths and still mark them as required.
+- If **any** of the matching workflows on the same SHA **have failed**, this
+  workflow will create a failure status
+- If we're still waiting, a pending status will be created that reports what
+  we're waiting for
+- If none of the listed workflows report a completed status via GitHub's API,
+  we'll refresh until we see a status
+
+## Setup
+
+- Add an workflow like the following:
+
+```yaml
+name: Required
+
+on:
+  workflow_run:
+    workflows:
+      - Check Transpiled JavaScript
+      - Continuous Integration
+      - Lint Codebase
+    types:
+      - completed
+
+permissions:
+  contents: read
+  actions: read
+  statuses: write
+
+jobs:
+  success:
+    if:
+      contains(fromJSON('["merge_group", "pull_request"]'),
+      github.event.workflow_run.event)
+    name: Check required workflow status
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      statuses: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: urcomputeringpal/optional-required-workflows@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status-name: Required
+          must-succeed-if-run: |
+            Check Transpiled JavaScript
+            Continuous Integration
+            Lint Codebase
+```
+
+- Use `CODEOWNERS` to protect the contents of this file on your default branch
+- Mark the 'Required' build as required in your repository settings

action.yml

@@ -1,6 +1,7 @@
-name: Required workflows
+name: Optional required workflows
 description: >-
-  Configure required workflows in your repo. Use path filters. Be free.
+  Configure required workflows in your repository. Use path filters. Leave your
+  GitHub org administrator alone.
 author: jnewland@urcomputeringpal.com
 # Add your action's branding here. This will appear on the GitHub Marketplace.
 branding: