Keep CODEOWNERS-Owned Pull Requests From Merging Without Review

id: codeowners-review-enforcer
namespace: company.team
description: |
  Enforce the CODEOWNERS review promise on a live repository. A webhook fires when a
  pull request opens, the GitHub API returns every open pull request in a single call,
  a Python verdict flags the ones still short of their required approving reviews, one
  GitHub issue is filed per gap with a Slack summary behind it, and any failure
  escalates to the ops channel instead of passing unnoticed.

triggers:
  - id: pr_opened
    type: io.kestra.plugin.core.trigger.Webhook
    description: GitHub or your merge bot POSTs here when a pull request opens, so
      enforcement starts the moment review becomes due.
    key: "{{ secret('CODEOWNERS_WEBHOOK_KEY') }}"

  - id: hourly_sweep
    type: io.kestra.plugin.core.trigger.Schedule
    description: Hourly safety net that re-checks every open pull request, shipped
      disabled until you switch it on after a clean manual run.
    cron: "0 * * * *"
    disabled: true

inputs:
  - id: repo
    type: STRING
    defaults: kestra-io/kestra
    description: Repository to enforce in owner/name form, for example kestra-io/kestra.

  - id: required_approvals
    type: INT
    defaults: 1
    description: How many approving reviews each CODEOWNERS-owned pull request needs
      before it counts as covered.

  - id: exclude_drafts
    type: BOOL
    defaults: true
    description: Skip draft pull requests, which cannot merge yet and should not be
      chased for review.

tasks:
  # --- 1. fetch open pull requests ---
  - id: fetch_open_prs
    type: io.kestra.plugin.core.http.Request
    description: Read all open pull requests from the GitHub REST API with a bearer
      token, one call instead of a request per pull request.
    uri: "https://api.github.com/repos/{{ inputs.repo }}/pulls?state=open"
    method: GET
    headers:
      Accept: "application/vnd.github+json"
      Authorization: "Bearer {{ secret('GITHUB_TOKEN') }}"
      X-GitHub-Api-Version: "2022-11-28"
      User-Agent: "codeowners-review-enforcer"
    retry:
      type: constant
      interval: PT3S
      maxAttempts: 3

  # --- 2. review verdict ---
  - id: evaluate_reviews
    type: io.kestra.plugin.scripts.python.Script
    description: Parse the pull request payload, live or fixture shaped with empty
      arrays included, count the approving reviews on each one, and publish the
      verdict with the missing-review list.
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    containerImage: python:3.11-slim
    inputFiles:
      prs.json: "{{ outputs.fetch_open_prs.body | toJson }}"
    script: |
      import json

      REPO = "{{ inputs.repo }}"
      REQUIRED = max(int("{{ inputs.required_approvals }}"), 1)
      EXCLUDE_DRAFTS = str("{{ inputs.exclude_drafts }}").strip().lower() in ("true", "1", "yes")

      def read_prs():
          try:
              with open("prs.json") as handle:
                  raw = handle.read().strip()
          except OSError:
              return []
          if not raw:
              return []
          try:
              data = json.loads(raw)
          except ValueError:
              return []
          while isinstance(data, str):
              try:
                  data = json.loads(data)
              except ValueError:
                  return []
          if isinstance(data, list):
              return data
          if isinstance(data, dict):
              for key in ("items", "pull_requests", "prs", "value"):
                  if isinstance(data.get(key), list):
                      return data[key]
          return []

      def approvals_of(pr):
          reviews = pr.get("reviews")
          if isinstance(reviews, list):
              return sum(1 for r in reviews
                         if isinstance(r, dict) and str(r.get("state", "")).upper() == "APPROVED")
          for key in ("approvals", "approved_reviews", "approving_review_count"):
              if key in pr:
                  try:
                      return max(int(pr[key]), 0)
                  except (TypeError, ValueError):
                      return 0
          if str(pr.get("review_decision", "")).upper() == "APPROVED":
              return REQUIRED
          return 0

      def reason_for(pr, approvals):
          requested = pr.get("requested_reviewers")
          if isinstance(requested, list) and requested:
              return "awaiting requested reviewers"
          for key in ("reviews", "approvals", "approved_reviews",
                      "approving_review_count", "review_decision"):
              if key in pr:
                  return "only %d of %d approvals on record" % (approvals, REQUIRED)
          return "no review evidence on record"

      def clean(text):
          flat = str(text or "untitled pull request")
          return " ".join(flat.replace("\\", "/").replace('"', "'").split())

      prs = [p for p in read_prs() if isinstance(p, dict)]
      records = []
      missing = []
      for pr in prs:
          state = str(pr.get("state", "open") or "open").lower()
          if state not in ("open", "none"):
              continue
          if EXCLUDE_DRAFTS and pr.get("draft"):
              continue
          approvals = approvals_of(pr)
          number = pr.get("number")
          title = pr.get("title") or "untitled pull request"
          user = pr.get("user")
          records.append({"number": number, "title": title, "approvals": approvals})
          if approvals < REQUIRED:
              missing.append({
                  "number": number,
                  "title": title,
                  "author": user.get("login", "unknown") if isinstance(user, dict) else "unknown",
                  "url": pr.get("html_url") or "",
                  "approvals": approvals,
                  "reason": reason_for(pr, approvals),
              })

      missing.sort(key=lambda m: (m["number"] is None,
                                  m["number"] if isinstance(m["number"], int) else 0))
      parts = ["#%s %s" % (m["number"], clean(m["title"])) for m in missing[:10]]
      if len(missing) > 10:
          parts.append("(+%d more)" % (len(missing) - 10))

      payload = {
          "repo": REPO,
          "required_approvals": REQUIRED,
          "open_prs": len(records),
          "prs": records,
          "missing_review_count": len(missing),
          "missing_reviews": missing,
          "missing_summary": "; ".join(parts) if parts else "no open pull request is missing a review",
          "verdict": "ACTION_REQUIRED" if missing else "COMPLIANT",
      }
      print("::" + json.dumps({"outputs": payload}, ensure_ascii=True) + "::")

  # --- 3. gate and escalate ---
  - id: review_gap_gate
    type: io.kestra.plugin.core.flow.If
    description: Branch on the verdict so covered repositories stay quiet and every
      uncovered pull request gets a ticket plus a channel alert.
    condition: "{{ outputs.evaluate_reviews.vars.missing_review_count > 0 }}"
    then:
      - id: file_issue_per_pull_request
        type: io.kestra.plugin.core.flow.Loop
        description: Walk the missing-review list and open one tracking issue per pull
          request, so each gap is assignable instead of buried in a chat
          message.
        values: "{{ outputs.evaluate_reviews.vars.missing_reviews }}"
        tasks:
          - id: create_review_issue
            type: io.kestra.plugin.github.issues.Create
            description: Open a labeled issue that names the pull request, its author, the
              approvals on record, and why review is still outstanding.
            jwtToken: "{{ secret('GITHUB_TOKEN') }}"
            repository: "{{ inputs.repo }}"
            title: "CODEOWNERS review missing for {{ inputs.repo }} pull request #{{
              item.value.number }}"
            labels:
              - codeowners
              - review-required
            body: |
              ## CODEOWNERS review still missing

              - Repository `{{ inputs.repo }}`
              - Pull request #{{ item.value.number }} - {{ item.value.title }}
              - Opened by {{ item.value.author }}
              - Approvals on record {{ item.value.approvals }} of {{ inputs.required_approvals }} required
              - Reason {{ item.value.reason }}
              - Pull request {{ item.value.url }}

              This change touches paths owned by CODEOWNERS and has not received the required
              approving review. Request the owners, or record the approval, before this merges.

              Filed by flow `{{ flow.id }}`, execution `{{ execution.id }}`.

      - id: summarize_review_gaps
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Post the verdict, the open pull request count, and the offending
          pull requests to the ops channel after the issues exist.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "CODEOWNERS review gap in {{ inputs.repo }} - {{ outputs.evaluate_reviews.vars.missing_review_count }} of {{ outputs.evaluate_reviews.vars.open_prs }} open pull request(s) still need {{ inputs.required_approvals }} approving review(s): {{ outputs.evaluate_reviews.vars.missing_summary }}. One GitHub issue per pull request is open. Verdict {{ outputs.evaluate_reviews.vars.verdict }}, execution {{ execution.id }}."
          }

    else:
      - id: report_all_clear
        type: io.kestra.plugin.core.log.Log
        description: Record the covered verdict so a clean sweep still leaves evidence
          in the execution history.
        message: "CODEOWNERS review sweep clean for {{ inputs.repo }} - all {{
          outputs.evaluate_reviews.vars.open_prs }} inspected open pull
          request(s) hold {{ inputs.required_approvals }} approving review(s).
          Verdict {{ outputs.evaluate_reviews.vars.verdict }}."

errors:
  - id: notify_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Escalate any failure to the ops channel with the execution id,
      because a sweep that dies silently reads as a clean sweep.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {"text": "FAILED: CODEOWNERS review enforcement for {{ inputs.repo }} in flow {{ flow.id }}, execution {{ execution.id }}. No review verdict was produced, verify GITHUB_TOKEN and the webhook trigger key."}

outputs:
  - id: verdict
    type: STRING
    description: COMPLIANT when every inspected pull request holds its required
      approvals, otherwise ACTION_REQUIRED.
    value: "{{ outputs.evaluate_reviews.vars.verdict }}"

  - id: open_prs
    type: INT
    description: Number of open, non-draft pull requests inspected in this sweep.
    value: "{{ outputs.evaluate_reviews.vars.open_prs }}"

  - id: missing_review_count
    type: INT
    description: How many inspected pull requests are short of the required
      approving reviews.
    value: "{{ outputs.evaluate_reviews.vars.missing_review_count }}"

  - id: missing_reviews
    type: ARRAY
    description: One entry per uncovered pull request with its number, title,
      author, approvals, and reason.
    value: "{{ outputs.evaluate_reviews.vars.missing_reviews | toJson }}"