BranchJanitor - GitHub stale branch cleaner

id: branchjanitor
namespace: company.team
description: Finds stale branches in a GitHub repo, deletes them, and reports
  the cleanup on Slack.

labels:
  project: branchjanitor
  team: github

inputs:
  - id: repo
    type: STRING
    displayName: "Repository"
    description: the repo whose branches to clean, as owner/repo
  - id: upstream_repo
    type: STRING
    displayName: "Upstream repository"
    description: for forks only, the upstream repo as owner/repo. PRs are looked up
      there, branches are cleaned on repo
    defaults: ""
  - id: stale_days
    type: INT
    displayName: "Stale threshold (days)"
    description: branches with no PR and no commit for this long count as abandoned
    defaults: 90
  - id: dry_run
    type: BOOL
    displayName: "Dry run"
    description: when true, only reports what would be deleted without deleting anything
    defaults: true
  - id: slack_webhook
    type: STRING
    displayName: "Slack Webhook URL"
    description: Incoming webhook URL of the Slack channel for the cleanup report

triggers:
  - id: schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: cleans up stale branches every Sunday morning
    cron: "0 8 * * 0"
    timezone: UTC
    inputs:
      repo: "your-org/your-repo"
      upstream_repo: ""
      stale_days: 90
      dry_run: true
      slack_webhook: "{{ secret('SLACK_WEBHOOK') }}"

tasks:
  - id: find_stale
    type: io.kestra.plugin.scripts.python.Script
    description: finds stale branches, never touching protected or in-progress ones
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
      user: "0"
    containerImage: python:3.11
    dependencies:
      - kestra
    outputFiles:
      - stale.txt
    script: |
      import json
      import urllib.request
      import urllib.parse
      from datetime import datetime, timezone, timedelta
      from kestra import Kestra

      repo = """{{ inputs.repo }}""".strip()
      upstream = """{{ inputs.upstream_repo }}""".strip()
      stale_days = int("""{{ inputs.stale_days }}""")
      dry_run = """{{ inputs.dry_run }}""".strip().lower() == "true"
      token = """{{ secret('GITHUB_TOKEN') }}"""
      owner, name = repo.split("/", 1)
      # fork workflow: PRs live on the upstream repo, branches live on the fork
      pr_repo = upstream if upstream else repo
      pr_owner, pr_name = pr_repo.split("/", 1)

      def api(method, path):
          req = urllib.request.Request(
              f"https://api.github.com{path}",
              method=method,
              headers={
                  "Authorization": f"Bearer {token}",
                  "Accept": "application/vnd.github+json",
                  "X-GitHub-Api-Version": "2022-11-28",
              },
          )
          with urllib.request.urlopen(req) as resp:
              body = resp.read().decode()
              return json.loads(body) if body else None

      def paged(path):
          out, page = [], 1
          while True:
              sep = "&" if "?" in path else "?"
              chunk = api("GET", f"{path}{sep}per_page=100&page={page}")
              if not chunk:
                  break
              out.extend(chunk)
              page += 1
          return out

      default_branch = api("GET", f"/repos/{owner}/{name}")["default_branch"]
      cutoff = datetime.now(timezone.utc) - timedelta(days=stale_days)

      stale = []
      for br in paged(f"/repos/{owner}/{name}/branches"):
          bname = br["name"]
          if bname == default_branch:
              continue  # never the default branch
          if br.get("protected"):
              continue  # never protected branches
          sha = br["commit"]["sha"]
          commit = api("GET", f"/repos/{owner}/{name}/commits/{sha}")
          committed_at = datetime.fromisoformat(
              commit["commit"]["author"]["date"].replace("Z", "+00:00")
          )
          head = f"{owner}:{urllib.parse.quote(bname, safe='')}"
          prs = api("GET", f"/repos/{pr_owner}/{pr_name}/pulls?head={head}&state=all")
          if any(p["state"] == "open" for p in prs):
              continue  # work in progress, never touch
          merged = any(p.get("merged_at") for p in prs)
          abandoned = not prs and committed_at < cutoff
          if merged or abandoned:
              age = (datetime.now(timezone.utc) - committed_at).days
              reason = "merged PR" if merged else f"no PR, last commit {age}d ago"
              stale.append({"name": bname, "reason": reason})

      with open("stale.txt", "w") as f:
          for s in stale:
              f.write(s["name"] + "\n")

      if dry_run:
          title = f"*BranchJanitor - dry run in '{repo}'*"
          tail = "would delete {n} branch(es). set dry_run to false to actually clean."
      else:
          title = f"*BranchJanitor - cleaned '{repo}'*"
          tail = "deleted {n} branch(es)."
      lines = [title, ""]
      for s in stale:
          lines.append(f"- *{s['name']}*: {s['reason']}")
      lines.append("")
      lines.append(tail.format(n=len(stale)))
      summary_text = "\n".join(lines)

      Kestra.outputs({
          'stale': stale,
          'count': len(stale),
          'summary_text': summary_text,
      })

  - id: maybe_clean
    type: io.kestra.plugin.core.flow.If
    description: only acts when there is something stale to report
    condition: "{{ outputs.find_stale.vars.count > 0 }}"
    then:
      - id: do_clean
        type: io.kestra.plugin.core.flow.If
        description: deletes the stale branches, live mode only
        condition: "{{ inputs.dry_run == false }}"
        then:
          - id: delete_branches
            type: io.kestra.plugin.scripts.python.Script
            description: deletes each stale branch through the GitHub API
            taskRunner:
              type: io.kestra.plugin.scripts.runner.docker.Docker
              user: "0"
            containerImage: python:3.11
            dependencies:
              - kestra
            script: |
              import urllib.request
              import urllib.parse

              repo = """{{ inputs.repo }}""".strip()
              token = """{{ secret('GITHUB_TOKEN') }}"""
              owner, name = repo.split("/", 1)

              with open("""{{ outputs.find_stale.outputFiles['stale.txt'] }}""") as f:
                  branches = [line.strip() for line in f if line.strip()]

              for b in branches:
                  ref = urllib.parse.quote(b, safe="")
                  req = urllib.request.Request(
                      f"https://api.github.com/repos/{owner}/{name}/git/refs/heads/{ref}",
                      method="DELETE",
                      headers={
                          "Authorization": f"Bearer {token}",
                          "Accept": "application/vnd.github+json",
                          "X-GitHub-Api-Version": "2022-11-28",
                      },
                  )
                  urllib.request.urlopen(req).read()
      - id: send_summary
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: posts the cleanup summary to Slack
        url: "{{ inputs.slack_webhook }}"
        messageText: "{{ outputs.find_stale.vars.summary_text }}"