GitHub Code Search Deprecated API Usage Drift Auditor with Kestra

id: github-code-search-deprecated-api-usage-drift-auditor
namespace: company.team

description: |
  Run a GitHub code search for a deprecated API or pattern that should have been migrated away
  from, classify the match count against a budget, auto-file a GitHub tracking issue listing
  every hit only when explicitly authorized, alert Slack otherwise, and log a governance audit
  trail either way.

inputs:
  - id: github_repository
    type: STRING
    displayName: GitHub repository
    description: Repository to search, in owner/repo form.
    defaults: "kestra-io/kestra"

  - id: search_query
    type: STRING
    displayName: Code search query
    description: GitHub code search keywords and qualifiers identifying the
      deprecated API or pattern, for example a deprecated client class name plus
      a language qualifier.
    defaults: "OldApiClient language:java"

  - id: max_allowed_matches
    type: INT
    displayName: Max allowed matches
    description: A search returning more than this many hits is classified over budget.
    defaults: 0

  - id: confirm_file_issue
    type: BOOL
    displayName: Confirm automatic issue filing
    description: When true, this flow is authorized to file a GitHub issue listing
      every remaining hit itself. When false, going over budget only alerts
      Slack so a human files the issue.
    defaults: false

tasks:
  - id: search_code
    type: io.kestra.plugin.github.code.Search
    description: Read-only probe. Searches code the token can access for
      search_query; nothing in the repository is changed.
    allowFailure: true
    oauthToken: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
    query: "{{ inputs.search_query }}"
    repository: "{{ inputs.github_repository }}"
    fetchType: FETCH

  - id: evaluate
    type: io.kestra.plugin.core.output.OutputValues
    description: Counts the matches GitHub's own search reported and classifies the
      result against max_allowed_matches, folding confirm_file_issue into the
      over-budget classification so the Switch branch needs no further nesting.
    values:
      match_count: "{{ outputs.search_code is not defined ? -1 :
        outputs.search_code.size }}"
      match_summary: >-
        {{ outputs.search_code is not defined ? '' : (({'rows':
        outputs.search_code.rows} | jq('[(.rows // [])[] | .path + " (" + .url +
        ")"] | join("; ")')) | first) }}
      severity: >-
        {{ outputs.search_code is not defined ? 'PROBE_FAILED' :
        ((outputs.search_code.size <= inputs.max_allowed_matches) ?
        'WITHIN_BUDGET' : (inputs.confirm_file_issue ? 'OVER_BUDGET_FILE_ISSUE'
        : 'OVER_BUDGET_NEEDS_HUMAN')) }}

  - id: route
    type: io.kestra.plugin.core.flow.Switch
    description: WITHIN_BUDGET just logs. OVER_BUDGET_FILE_ISSUE performs the safe
      remediation (filing a tracking issue changes nothing in the code itself)
      only when confirm_file_issue authorizes it. OVER_BUDGET_NEEDS_HUMAN and
      PROBE_FAILED both alert Slack instead.
    value: "{{ outputs.evaluate.values.severity }}"
    cases:
      "WITHIN_BUDGET":
        - id: log_within_budget
          type: io.kestra.plugin.core.log.Log
          message: "{{ outputs.search_code.size }} match(es) for '{{ inputs.search_query
            }}' in {{ inputs.github_repository }}, within the budget of {{
            inputs.max_allowed_matches }}."
      "OVER_BUDGET_FILE_ISSUE":
        - id: file_tracking_issue
          type: io.kestra.plugin.github.issues.Create
          description: Files a tracking issue listing every remaining hit now that
            confirm_file_issue explicitly authorizes this flow to act. Creating
            an issue changes nothing in the codebase itself.
          oauthToken: "{{ secret('GITHUB_ACCESS_TOKEN') }}"
          repository: "{{ inputs.github_repository }}"
          title: "Deprecated API usage over budget: {{ inputs.search_query }}"
          body: "Automated audit found {{ outputs.search_code.size }} match(es) for `{{
            inputs.search_query }}`, over the budget of {{
            inputs.max_allowed_matches }}. Locations: {{
            outputs.evaluate.values.match_summary }}. Execution {{ execution.id
            }}."
          labels:
            - tech-debt
        - id: alert_issue_filed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'OVER_BUDGET_FILE_ISSUE: ' ~ outputs.search_code.size ~ ' match(es) for ' ~ "'" ~ inputs.search_query ~ "'" ~ ' in ' ~ inputs.github_repository ~ ', over the budget of ' ~ inputs.max_allowed_matches ~ '. Filed tracking issue ' ~ outputs.file_tracking_issue.issueUrl ~ '.'} | toJson }}
      "OVER_BUDGET_NEEDS_HUMAN":
        - id: alert_over_budget
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'OVER_BUDGET_NEEDS_HUMAN: ' ~ outputs.search_code.size ~ ' match(es) for ' ~ "'" ~ inputs.search_query ~ "'" ~ ' in ' ~ inputs.github_repository ~ ', over the budget of ' ~ inputs.max_allowed_matches ~ '. Locations: ' ~ outputs.evaluate.values.match_summary ~ '. Set confirm_file_issue to true to let this flow file a tracking issue automatically, or file one manually now.'} | toJson }}
      "PROBE_FAILED":
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'PROBE_FAILED: GitHub code search failed for ' ~ inputs.github_repository ~ '. Check the token scope and that the repository is correct.'} | toJson }}

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "GitHub code search deprecated API usage drift auditor complete for {{
      inputs.github_repository }}: severity {{ outputs.evaluate.values.severity
      }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'GitHub code search deprecated API usage drift auditor failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: weekly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled. Enable once GITHUB_ACCESS_TOKEN and
      SLACK_WEBHOOK_URL are set and the inputs point at a real repository and
      deprecated-pattern query; confirm_file_issue stays false by default so
      going over budget alerts a human rather than auto-filing until you
      deliberately opt in.
    cron: "0 8 * * 1"
    disabled: true
    inputs:
      github_repository: "kestra-io/kestra"
      search_query: "OldApiClient language:java"
      max_allowed_matches: 0
      confirm_file_issue: false

A deprecated internal API, a banned library call, or a function slated for removal rarely disappears from a codebase on schedule; it lingers until a migration deadline arrives and someone has to go find every remaining caller by hand. GitHub's own code search can find those callers in one query, but it has no concept of a migration budget and no way to turn a match count into a tracked action. This blueprint runs that search on a schedule, reports exactly how far the codebase is from zero remaining matches, and only files a tracking issue once you have explicitly said this flow is allowed to.

This blueprint was created by Mohit Jeswani.

How it works

search_code (io.kestra.plugin.github.code.Search) runs search_query against github_repository and returns every matching file's path and URL. Read-only; nothing in the repository is changed. allowFailure: true covers an API or auth error without failing the flow outright.
evaluate (io.kestra.plugin.core.output.OutputValues) reads the match count GitHub's own search already reports and classifies it as WITHIN_BUDGET, OVER_BUDGET_FILE_ISSUE, OVER_BUDGET_NEEDS_HUMAN, or PROBE_FAILED, folding confirm_file_issue into the over-budget classification itself.
route (io.kestra.plugin.core.flow.Switch):
- WITHIN_BUDGET: logs that the match count is inside budget.
- OVER_BUDGET_FILE_ISSUE: runs io.kestra.plugin.github.issues.Create (the safe remediation, since filing an issue only adds visibility and changes nothing in the code), then posts a Slack notice linking the filed issue.
- OVER_BUDGET_NEEDS_HUMAN / PROBE_FAILED: posts a Slack alert instead of acting.
summary logs the severity, closing the governance cycle.
errors alerts Slack if the flow itself fails, for example an expired token.

What you get

A migration budget enforced against GitHub's own search results, not a stale spreadsheet of "files to fix" that nobody updates.
The exact file paths and URLs in both the Slack alert and the filed issue, so whoever picks it up can jump straight to the remaining callers.
A tracking issue that only ever gets filed once you have explicitly authorized it, so this can run unattended on a schedule without surprising anyone.

Who it's for

Platform and engineering-productivity teams running a deprecation or migration deadline who need the remaining caller count enforced, not just announced once.
Teams evaluating the GitHub plugin who want a worked example of code.Search used as a standing governance audit, distinct from this repo's existing GitHub blueprints, which cover workflow runs, commit search, and issue/PR creation rather than searching code content itself.

Why orchestrate this with Kestra

GitHub's code search answers one query at a time; it has no scheduler, no budget policy, and no Slack integration of its own. Kestra keeps search_query, max_allowed_matches, and confirm_file_issue as flow inputs, turns a raw hit count into a budget decision, and keeps a full execution history of every audit and whether a tracking issue was filed.

Prerequisites

A GitHub personal access token with access to search code in the target repository.
A repository with at least one real hit for search_query to confirm the over-budget path, and the ability to drop it below max_allowed_matches to confirm the compliant path.
A Slack incoming webhook URL.

GitHub is a hosted SaaS platform with no official standalone Docker image, so search_code cannot be exercised against a local container; validate against a real repository on a free GitHub account first.

Secrets

GITHUB_ACCESS_TOKEN: the GitHub personal access token used by search_code and file_tracking_issue. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_GITHUB_ACCESS_TOKEN.
SLACK_WEBHOOK_URL: used by all three Slack alert cases and the errors block. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_SLACK_WEBHOOK_URL.

Inputs

Input	Default	Purpose
`github_repository`	`kestra-io/kestra`	Repository to search
`search_query`	`OldApiClient language:java`	Deprecated API or pattern to find
`max_allowed_matches`	`0`	Hit count above which the search is over budget
`confirm_file_issue`	`false`	Authorizes this flow to file a tracking issue itself

Outputs

{{ outputs.search_code.rows }} / .size: the matching files and how many there are, as GitHub's code search reports them.
{{ outputs.evaluate.values.match_count }} / .match_summary: the match count and a semicolon-joined path (url) summary of every hit.
{{ outputs.evaluate.values.severity }}: WITHIN_BUDGET, OVER_BUDGET_FILE_ISSUE, OVER_BUDGET_NEEDS_HUMAN, or PROBE_FAILED.

Pitfalls

code.Search's own Javadoc examples do not mention that its typed Output (inherited from AbstractGithubSearchTask) exposes a direct size field; verified by reading AbstractGithubSearchTask.java directly, since relying on rows | length instead would still work but size is simpler and is what this blueprint uses.
GitHub's code search API indexes with a short delay and excludes forks, archived repositories, and files over roughly 384 KB by default; a very recent commit or a match in an oversized file can be invisible to search_query for a short time or permanently.
confirm_file_issue applies to the whole flow, not one specific audit; a scheduled run with it set to true files a new issue every time the match count is over budget, so pair it with a search scoped tightly enough that repeated filing is actually useful, or extend the flow to check for an already-open issue first.

Quick start

Add the GITHUB_ACCESS_TOKEN and SLACK_WEBHOOK_URL secrets.
Set github_repository and search_query to a real repository and a pattern with at least one known match.
Run the flow manually with confirm_file_issue: false and confirm alert_over_budget fires.
Run again with confirm_file_issue: true and confirm file_tracking_issue creates an issue and alert_issue_filed fires with its URL.
Lower the match count below max_allowed_matches (or raise the budget) and confirm log_within_budget fires.
Enable the weekly trigger once the inputs reflect your real migration policy.

How to extend

Chain a check of currently open issues with a matching title before file_tracking_issue runs, so a repeated over-budget audit updates one issue instead of filing a new one each time.
Loop over several search_query/github_repository pairs with io.kestra.plugin.core.flow.ForEach to enforce more than one deprecation budget in a single scheduled run.
Add a second, stricter max_allowed_matches threshold that fails the execution outright (via io.kestra.plugin.core.execution.Fail) once a hard deadline passes, instead of only alerting.

GitHub Code Search Deprecated API Usage Drift Auditor

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Outputs

Pitfalls

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

GitHub Code Search Deprecated API Usage Drift Auditor

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Outputs

Pitfalls

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Kafka ACL Baseline Restore Guard

Kafka Client Quota Guard

Self-heal Kafka Connect connectors with a restart budget and escalation

Kafka ACL Overly Broad Grant Audit

Archive ownerless failed Pod diagnostics before cleanup

Kafka Connect Paused Connector Resume Guard

New to Kestra?