Rename reusable-workflow-notification to workflow-failure-issue and add consumer docs

.github/CODEOWNERS

@@ -6,9 +6,13 @@
 
 * @open-telemetry/shared-workflows-approvers
 
-# Unlike typical shared workflows, the pull request dashboard workflow runs entirely
-# in this repository.
+# Pull request dashboard
+pull-request-dashboard/** @open-telemetry/shared-workflows-approvers @trask
 .github/scripts/pull-request-dashboard/** @open-telemetry/shared-workflows-approvers @trask
 .github/workflows/pull-request-dashboard.yml @open-telemetry/shared-workflows-approvers @trask
 .github/workflows/pull-request-dashboard-repo.yml @open-telemetry/shared-workflows-approvers @trask
 .github/workflows/pull-request-dashboard-deploy-webhook.yml @open-telemetry/shared-workflows-approvers @trask
+
+# Workflow failure issue
+workflow-failure-issue/** @open-telemetry/shared-workflows-approvers @trask
+.github/workflows/workflow-failure-issue.yml @open-telemetry/shared-workflows-approvers @trask

.github/workflows/pull-request-dashboard.yml

@@ -227,9 +227,8 @@ jobs:
         )
       )
     permissions:
-      contents: read
       issues: write # needed to open/close the hourly failure tracking issue
-    uses: ./.github/workflows/reusable-workflow-notification.yml
+    uses: ./.github/workflows/workflow-failure-issue.yml
     with:
       # A superseded per-repo publish is cancelled (publish-dashboard uses
       # cancel-in-progress: true), so count cancelled as success here to avoid

.github/workflows/reusable-workflow-notification.yml → .github/workflows/workflow-failure-issue.yml

@@ -1,6 +1,5 @@
-# this is useful because notifications for scheduled workflows are only sent to the user who
-# initially created the given workflow
-name: Reusable - Workflow notification
+# Reusable workflow — see /workflow-failure-issue/README.md for consumer documentation.
+name: Workflow failure issue
 
 on:
   workflow_call:
@@ -9,24 +8,19 @@ on:
         type: boolean
         required: true
 
-permissions:
-  contents: read
+permissions: {}
 
 jobs:
-  workflow-notification:
+  workflow-failure-issue:
     name: Open or close workflow failure issue
     permissions:
-      contents: read
       issues: write # needed to open, comment on, and close workflow failure issues
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
-
       - name: Open issue or add comment if issue already open
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
           INPUT_SUCCESS: ${{ inputs.success }}
         run: |
           set -euo pipefail

README.md

@@ -11,6 +11,7 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for how to propose a new shared workf
 | [First-time contributor](./first-time-pr/) | Reusable workflow that welcomes first-time contributors on `pull_request_target: opened`: applies a label and posts a customizable welcome comment. | Call via `uses:` from your repo's `pull_request_target` workflow. See the [First-time contributor README](./first-time-pr/README.md) for the snippet. |
 | [Pull Request Dashboard](./pull-request-dashboard/) | Centrally-executed workflow that builds a per-repository pull request triage dashboard (issue body, status, Slack notifications) for opted-in repositories. | Add your repository to [`repositories.json`](./.github/scripts/pull-request-dashboard/repositories.json) and follow the setup in the [workflow's README](./pull-request-dashboard/README.md). |
 | [Survey on merged PR](./survey-on-merged-pr/) | Reusable workflow that posts a survey link to a merged PR when the author is a new contributor. | Call via `uses:` from your repo's `pull_request_target: closed` workflow. See the [Survey on merged PR README](./survey-on-merged-pr/README.md) for the snippet. |
+| [Workflow failure issue](./workflow-failure-issue/) | Reusable workflow that tracks a workflow's pass/fail state by opening, commenting on, and closing a GitHub issue in the calling repository — useful for scheduled workflows whose failure notifications otherwise reach only a single user. | Call via `uses:` from a final `if: always()` job in the workflow you want to monitor. See the [Workflow failure issue README](./workflow-failure-issue/README.md) for the snippet. |
 | [Zizmor](./zizmor/) | Static analysis of GitHub Actions workflows for security issues using [zizmor](https://github.com/zizmorcore/zizmor). | Call via `uses:` from your repo's workflow. See the [Zizmor README](./zizmor/README.md) for the snippet. |
 
 ## Maintainers

workflow-failure-issue/README.md

@@ -0,0 +1,50 @@
+# Workflow failure issue
+
+Reusable GitHub Actions workflow that tracks the pass/fail state of another
+workflow (typically a scheduled one) by opening, commenting on, and closing a
+GitHub issue in the calling repository.
+
+This is useful because GitHub notifies only a single user of scheduled-workflow
+failures. Per the [GitHub docs on scheduled workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#actor-for-scheduled-workflows):
+
+> Notifications for scheduled workflows are sent to the user who last modified
+> the cron syntax in the workflow file.
+
+By opening a tracking issue instead, the failure is visible to the whole team.
+
+Behavior:
+
+- On failure, if no tracking issue is open, a new issue titled
+  `Workflow failed: <workflow name> (#<run number>)` is created.
+- On a subsequent failure while an issue is already open, a comment linking to
+  the failing run is added.
+- On success, any open tracking issue is closed.
+
+## How to use
+
+Add a final job to the workflow you want to monitor. It must run after the jobs
+you care about, use `if: always()` so it also runs when they fail, and grant
+`issues: write`:
+
+```yaml
+jobs:
+  # ... your jobs (e.g. build) ...
+
+  workflow-failure-issue:
+    permissions:
+      issues: write
+    needs:
+      - build
+    if: always()
+    uses: open-telemetry/shared-workflows/.github/workflows/workflow-failure-issue.yml@<sha-or-tag>
+    with:
+      success: ${{ needs.build.result == 'success' }}
+```
+
+Pin `<sha-or-tag>` to a commit SHA or release tag in this repository.
+
+### Inputs
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `success` | boolean | yes | Whether the monitored jobs succeeded. Pass `true` to close any open tracking issue, `false` to open or comment on one. |