GitHub Actions Orphaned Secret Reference Gate

id: github-actions-orphaned-secret-reference-gate
namespace: company.team

description: |
  Reconcile what a repository's GitHub Actions workflows actually reference against what
  secrets are actually configured in that repository's own settings. A workflow that references
  `secrets.SOME_TOKEN` when that secret was renamed or deleted does not fail to parse, it just
  silently resolves to an empty string, breaking a step in a way nobody notices until something
  downstream fails for no obvious reason. This blueprint finds those orphaned references before
  they bite, and separately flags configured secrets no workflow references at all.

inputs:
  - id: repository
    type: STRING
    displayName: Repository
    description: owner/repo whose .github/workflows files and configured Actions
      secrets are reconciled.
    defaults: kestra-io/kestra

  - id: confirm_file_issue
    type: BOOL
    displayName: Confirm issue filing
    description: When true, this flow is authorized to open a tracking issue on
      findings in addition to the Slack alert. When false, findings only alert
      Slack.
    defaults: false

tasks:
  - id: search_workflow_files
    type: io.kestra.plugin.github.code.Search
    description: Finds every file under .github/workflows in the target repository;
      each hit's download_url is fetched directly in the next task to read the
      actual YAML content, since code search only returns file metadata, not
      file bodies.
    oauthToken: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
    query: "path:.github/workflows"
    repository: "{{ inputs.repository }}"
    fetchType: FETCH

  - id: list_configured_secrets
    type: io.kestra.plugin.core.http.Request
    description: GitHub's REST API only ever returns configured secret names, never
      values, which is exactly what this reconciliation needs and all it should
      ever have access to.
    uri: "https://api.github.com/repos/{{ inputs.repository }}/actions/secrets"
    method: GET
    headers:
      Authorization: "Bearer {{ secret('GITHUB_ACCESS_TOKEN') }}"
      Accept: "application/vnd.github+json"
    options:
      allowFailed: true

  - id: extract_and_reconcile
    type: io.kestra.plugin.scripts.python.Script
    description: Downloads every matched workflow file's raw content, regex-extracts
      every secrets.NAME reference, and diffs the referenced-name set against
      the configured-name set from list_configured_secrets to find orphaned
      references and unused secrets.
    env:
      GITHUB_TOKEN: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
      WORKFLOW_FILES_JSON: "{{ outputs.search_workflow_files.rows | toJson }}"
      CONFIGURED_SECRETS_BODY: "{{ outputs.list_configured_secrets.code == 200 ?
        outputs.list_configured_secrets.body : '{}' }}"
    script: |
      import json
      import os
      import re
      import urllib.request

      github_token = os.environ["GITHUB_TOKEN"]
      workflow_files = json.loads(os.environ.get("WORKFLOW_FILES_JSON") or "[]")

      try:
          configured_secrets_raw = json.loads(os.environ["CONFIGURED_SECRETS_BODY"])
          configured_names = set(s["name"] for s in configured_secrets_raw.get("secrets", []))
      except Exception:
          configured_names = set()

      secret_pattern = re.compile(r"secrets\.([A-Za-z0-9_]+)")
      secret_to_files = {}

      for f in workflow_files:
          download_url = f.get("download_url")
          path = f.get("path") or f.get("name") or "unknown"
          if not download_url:
              continue
          req = urllib.request.Request(
              download_url,
              headers={"Authorization": f"Bearer {github_token}"}
          )
          try:
              with urllib.request.urlopen(req, timeout=15) as resp:
                  content = resp.read().decode("utf-8", errors="replace")
          except Exception:
              continue
          for name in set(secret_pattern.findall(content)):
              secret_to_files.setdefault(name, set()).add(path)

      referenced_names = set(secret_to_files.keys())
      orphaned = sorted(referenced_names - configured_names)
      unused = sorted(configured_names - referenced_names)

      orphaned_detail = "; ".join(
          f"{name} (referenced in {', '.join(sorted(secret_to_files[name]))})" for name in orphaned
      )

      if orphaned:
          severity = "ORPHANED_REFERENCES_FOUND"
      elif unused:
          severity = "UNUSED_SECRETS_FOUND"
      else:
          severity = "HEALTHY"

      from kestra import Kestra
      Kestra.outputs({
          "severity": severity,
          "orphaned": orphaned,
          "orphaned_detail": orphaned_detail,
          "unused": unused,
          "unused_count": len(unused),
          "orphaned_count": len(orphaned),
          "referenced_count": len(referenced_names),
          "configured_count": len(configured_names),
      })

  - id: route
    type: io.kestra.plugin.core.flow.Switch
    description: ORPHANED_REFERENCES_FOUND outranks UNUSED_SECRETS_FOUND, since a
      missing secret breaks a workflow on its next run while an unused one is
      only cleanup. Both alert Slack immediately; filing a tracking issue is a
      separate, explicitly authorized action in either branch.
    value: "{{ outputs.extract_and_reconcile.vars.severity }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "{{ inputs.repository }}: every secrets.* reference in
            .github/workflows matches a configured secret, and every configured
            secret is referenced somewhere."
      "UNUSED_SECRETS_FOUND":
        - id: alert_unused
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'UNUSED_SECRETS_FOUND in ' ~ inputs.repository ~ ': ' ~ outputs.extract_and_reconcile.vars.unused_count ~ ' configured secret(s) are never referenced in any workflow under .github/workflows: ' ~ (outputs.extract_and_reconcile.vars.unused | join(", ")) ~ ". No workflow will break if they stay, but they're worth a look before someone assumes they do something."} | toJson }}
        - id: file_unused_issue
          type: io.kestra.plugin.core.flow.If
          condition: "{{ inputs.confirm_file_issue }}"
          then:
            - id: create_unused_issue
              type: io.kestra.plugin.github.issues.Create
              oauthToken: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
              repository: "{{ inputs.repository }}"
              title: "Secret hygiene: {{ outputs.extract_and_reconcile.vars.unused_count }}
                configured Actions secret(s) never referenced"
              labels:
                - secret-hygiene
              body: |
                Configured in repository settings but not referenced by `secrets.NAME` in any workflow under `.github/workflows`:

                {{ outputs.extract_and_reconcile.vars.unused | join("\n") }}

                Filed automatically by the GitHub Actions orphaned secret reference gate (execution {{ execution.id }}). Confirm each one is genuinely unused (not read by a non-Actions integration) before removing it.
      "ORPHANED_REFERENCES_FOUND":
        - id: alert_orphaned
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'ORPHANED_REFERENCES_FOUND in ' ~ inputs.repository ~ ': ' ~ outputs.extract_and_reconcile.vars.orphaned_count ~ ' secrets.* reference(s) in .github/workflows point at a secret that is not configured on this repository, so it resolves to an empty string on the next run: ' ~ outputs.extract_and_reconcile.vars.orphaned_detail ~ ". Execution " ~ execution.id ~ "."} | toJson }}
        - id: file_orphaned_issue
          type: io.kestra.plugin.core.flow.If
          condition: "{{ inputs.confirm_file_issue }}"
          then:
            - id: create_orphaned_issue
              type: io.kestra.plugin.github.issues.Create
              oauthToken: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
              repository: "{{ inputs.repository }}"
              title: "Secret hygiene: {{ outputs.extract_and_reconcile.vars.orphaned_count }}
                workflow secret reference(s) have no matching configured secret"
              labels:
                - secret-hygiene
                - bug
              body: |
                These `secrets.NAME` references in `.github/workflows` resolve to an empty string today, because no secret by that name is configured on this repository:

                {{ outputs.extract_and_reconcile.vars.orphaned_detail }}

                Filed automatically by the GitHub Actions orphaned secret reference gate (execution {{ execution.id }}). Either configure the missing secret or remove the dead reference.

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "Secret reference reconciliation for {{ inputs.repository }} complete:
      severity {{ outputs.extract_and_reconcile.vars.severity }}, {{
      outputs.extract_and_reconcile.vars.referenced_count }} referenced / {{
      outputs.extract_and_reconcile.vars.configured_count }} configured."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'GitHub Actions orphaned secret reference gate failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: daily_sweep
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 6 * * *"