Merge pull request #4 from urcomputeringpal/demo

docs, demo

.github/workflows/check-dist.yml

@@ -13,6 +13,10 @@ on:
   pull_request:
     branches:
       - main
+    paths:
+      - '**/*.ts'
+      - '**/*.json'
+      # - .github/workflows/check-dist.yml
   push:
     branches:
       - main

.github/workflows/ci.yml

@@ -4,6 +4,10 @@ on:
   pull_request:
     branches:
       - main
+    paths:
+      - '**/*.ts'
+      - '**/*.json'
+      # - .github/workflows/ci.yml
   push:
     branches:
       - main

.github/workflows/required.yml

@@ -1,10 +1,22 @@
-# Create a Status named 'Required' that reports the observed conclusion of all
-# matching WorkflowRuns on the same `head_sha` as the observed WorkflowRun.
 name: Required
 
 on:
   workflow_run:
     workflows:
+      # Add workflows here to mark them as required if observed on pull request
+      # or merge group events. If any of them fail, the a failing status will
+      # be created. At least one of these workflows must succeed for this
+      # workflow to succeed.
+      #
+      # Workflows in this list **may** use `paths` to match only run when
+      # certain files or directories change. As opposed to the traditional
+      # required status setting on GitHub repositories, a PR will not be
+      # blocked if it skips a workflow in this list.
+      #
+      # !!! IMPORTANT !!! ##
+      # This list must match the list passed to must-succeed-if-run argument
+      # at the end of this workflow file
+      #
       - Check Transpiled JavaScript
       - Continuous Integration
       - Lint Codebase
@@ -21,11 +33,11 @@ run-name: >
   github.event.workflow_run.name }}
 
 jobs:
-  success:
+  status:
     if:
       contains(fromJSON('["merge_group", "pull_request"]'),
       github.event.workflow_run.event)
-    name: Check required workflow status
+    name: Create status summarizing conclusion of required workflows
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -37,6 +49,8 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           status-name: Required
+          # !!! IMPORTANT !!! ##
+          # This list must match the list passed to on.workflow_run.workflows
           must-succeed-if-run: |
             Check Transpiled JavaScript
             Continuous Integration

README.md

@@ -6,28 +6,69 @@ 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.
 
+## Problem(s)
+
+### Required status checks are challenging to manage without overly broad permissions
+
+GitHub's
+[required status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks)
+are configured via branch protection rules. People with **admin permissions** or
+a _custom role_ with the "edit repository rules" permission to a repository can
+[manage branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule).
+Only organizations that use GitHub Enterprise Cloud can
+[create custom repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization).
+
+### Changes to required status checks are not tracked in the repository
+
+Changes to required status checks are not tracked in the repository. This makes
+it hard to coordinate, document, and review changes to required status checks.
+And because of the above permissions challenges, it's sometimes someone else's
+job to change this setting. As a result, it can sometimes be hard to know when
+the change will take place.
+
+### Required status checks are incompatible with path filters
+
+Required status checks are also
+[incompatible with several other Actions features](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks#handling-skipped-but-required-checks):
+
+> If a workflow is skipped due to path filtering, branch filtering or a commit
+> message, then checks associated with that workflow will remain in a "Pending"
+> state. A pull request that requires those checks to be successful will be
+> blocked from merging.
+
+## Solution
+
+This Action lets you define a list of workflows that are required to pass on a
+pull request **if they are observed to have started once the first one
+completes**. It will check to see if those workflows have passed on the same
+SHA. If they have, it will create a successful status. If they haven't, it will
+create a failing status.
+
 ## 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
+- When **at least one** of those workflows **complete** on a PR, this workflow
+  will check to see if **any other listed workflows** are present on the same
+  SHA
+- If **any** of the matching workflows on the same SHA **have failed**, this
+  workflow will create a failure status
 - 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**
+  workflow will create a successful status
+- If **some** of the matching workflows on the same SHA **are missing**, this
+  workflow **will still create a successful status** if at least one has passed
   - 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:
+### Workflow
+
+Add an workflow like the following to your repository:
 
 ```yaml
 name: Required
@@ -69,5 +110,31 @@ jobs:
             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
+### `CODEOWNERS`
+
+Add this file to `CODEOWNERS` to protect the contents of this file on your
+default branch:
+
+```plaintext
+.github/workflows/required.yml @your-org/your-repo-admins
+```
+
+### Required workflows
+
+Have a GitHub organization admin or someone with the the "edit repository rules"
+permission on your repository require the `Required` status in your
+[branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule).
+
+Offer to your GitHub organization admin to be listed on the `CODEOWNERS` line,
+either;
+
+- As the only entry (retains previous behavior, except they just have to
+  approve)
+- As an additional entry (either they or you can approve)
+- Or not at all (they delegate the review/approval of required status on this
+  repository checks to your team)
+
+## Caveats / Possible future enhancements
+
+- Many workflows can generate statuses of the same name. In the future, optional
+  support for matching on `event.workflow_run.path` may be desirable.