Add PR linked-issue check action and workflow

Introduce a composite GitHub Action that verifies a pull request has at least one linked issue via the GraphQL closingIssuesReferences field, plus a reusable workflow to run it. Adds action implementation (.github/actions/check-linked-issue/action.yml) and documentation (README.md) and a reusable workflow (.github/workflows/check-issue.yml). The action uses actions/github-script to query linked issues and fails the step if none are found; the workflow demonstrates usage and required permissions (contents: read, pull-requests: read). Also removes a placeholder .gitkeep file.

Signed-off-by: John McCall <john@overturemaps.org>

Author: lowlydba

.github/actions/.gitkeep

@@ -0,0 +1,122 @@
+# Check Linked Issue
+
+A composite GitHub Action that verifies a pull request has at least one linked GitHub issue.
+
+## Explanation
+
+### What it does
+
+This action queries the GitHub GraphQL API for `closingIssuesReferences` on a
+pull request. It detects issues linked by:
+
+- Body keywords: `Fixes #123`, `Closes #456`, `Resolves owner/repo#789`
+- Manual linking via the GitHub UI sidebar
+
+If no linked issues are found, the step fails with a message guiding the author
+to link one.
+
+### Why GraphQL over regex
+
+| Approach | Body keywords | UI-linked issues | Cross-repo refs | Format-proof |
+|----------|:---:|:---:|:---:|:---:|
+| Regex on PR body | ✅ | ❌ | Fragile | ❌ |
+| `closingIssuesReferences` | ✅ | ✅ | ✅ | ✅ |
+
+The GraphQL approach reflects GitHub's actual internal linkage rather than
+parsing text, making it reliable across formatting styles and linking methods.
+
+## How-to guides
+
+### Use the reusable workflow (recommended)
+
+The simplest way to adopt this check from any repo in the OvertureMaps
+organization. Create a workflow file in your repo:
+
+```yaml
+# .github/workflows/check-issue.yml
+name: Check Linked Issue
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  check-issue:
+    uses: OvertureMaps/workflows/.github/workflows/check-issue.yml@main
+```
+
+No checkout step is needed — GitHub resolves the reusable workflow and its
+actions automatically.
+
+### Use the composite action directly from this repo
+
+If you need to combine this check with other steps in an existing job, check out
+the action and reference it locally:
+
+```yaml
+# .github/workflows/pr-checks.yml
+name: PR Checks
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout workflows repo
+        uses: actions/checkout@v4
+        with:
+          repository: OvertureMaps/workflows
+          sparse-checkout: .github/actions/check-linked-issue
+          path: .workflows
+
+      - name: Check for linked issue
+        uses: ./.workflows/.github/actions/check-linked-issue
+
+      # ... additional steps in the same job
+```
+
+### Use the composite action within the workflows repo
+
+When referencing the action from a workflow in this same repository, use a
+relative path without a checkout step:
+
+```yaml
+steps:
+  - uses: ./.github/actions/check-linked-issue
+```
+
+## Reference
+
+### Permissions
+
+Requires the default `GITHUB_TOKEN` with:
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: read
+```
+
+For private repos, these permissions allow the token to read PR metadata and
+query linked issues. Cross-repo issue detection is limited to public repos and
+repos within the same organization that the token has access to.
+
+### Inputs
+
+This action has no inputs.
+
+### Outputs
+
+This action has no outputs. It either passes or fails the step.
+
+### Supported trigger events
+
+The action reads `context.payload.pull_request.number`, so it must run on a
+`pull_request` or `pull_request_target` event.

.github/actions/check-linked-issue/README.md

@@ -0,0 +1,56 @@
+---
+name: Check Linked Issue
+description: >
+  Checks that a pull request has at least one linked GitHub issue via
+  closingIssuesReferences. Covers 'Fixes #123', 'Closes owner/repo#456',
+  and issues linked manually through the GitHub UI.
+
+runs:
+  using: composite
+  steps:
+    - name: Check for linked issue via GraphQL
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prNumber = context.payload.pull_request.number;
+          const { owner, repo } = context.repo;
+
+          const query = `
+            query($owner: String!, $repo: String!, $number: Int!) {
+              repository(owner: $owner, name: $repo) {
+                pullRequest(number: $number) {
+                  closingIssuesReferences(first: 10) {
+                    nodes {
+                      number
+                      title
+                      state
+                      url
+                    }
+                  }
+                }
+              }
+            }
+          `;
+
+          const result = await github.graphql(query, {
+            owner,
+            repo,
+            number: prNumber
+          });
+
+          const issues =
+            result.repository.pullRequest.closingIssuesReferences.nodes;
+
+          if (!issues || issues.length === 0) {
+            core.setFailed(
+              "This PR does not reference any linked issues. " +
+              "Please link an issue using 'Fixes #123', " +
+              "'Closes OvertureMaps/other-repo#123', or the GitHub UI " +
+              "(https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)"
+            );
+          } else {
+            core.info("Linked issues found:");
+            issues.forEach(issue => {
+              core.info(`  #${issue.number} - ${issue.title} (${issue.state}) ${issue.url}`);
+            });
+          }

.github/actions/check-linked-issue/action.yml

@@ -0,0 +1,47 @@
+---
+# Reusable workflow to enforce that PRs have a linked GitHub issue.
+#
+# Uses the check-linked-issue composite action which queries GraphQL
+# closingIssuesReferences to detect linked issues, covering:
+#   - Body keywords: Fixes #123, Closes #456, Resolves owner/repo#789
+#   - Issues manually linked via the GitHub UI
+#
+# Usage: Reference this workflow from any repo in the OvertureMaps organization.
+#
+# Example (.github/workflows/check-issue.yml):
+#   name: Check Linked Issue
+#   on:
+#     pull_request:
+#       types: [opened, edited, synchronize]
+#   jobs:
+#     check-issue:
+#       uses: OvertureMaps/workflows/.github/workflows/check-issue.yml@main
+#
+name: Check Linked Issue
+
+on:
+  workflow_call:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-linked-issue:
+    name: Check Linked Issue
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout workflows repo
+        uses: actions/checkout@v4
+        with:
+          repository: OvertureMaps/workflows
+          sparse-checkout: .github/actions/check-linked-issue
+          path: .workflows
+
+      - name: Check for linked issue
+        uses: ./.workflows/.github/actions/check-linked-issue