Analyze Upstream Release Breaking Changes with AI and Slack Alerts

id: github-release-breaking-change-ai-advisor
namespace: company.devops

description: |
  Inspects upstream GitHub repository releases using AI to detect breaking API changes,
  extract actionable migration steps, calculate upgrade risk scores, and dispatch
  advisory briefs to Slack with stateful KV cursor tracking to prevent duplicate alerts.

inputs:
  - id: repository
    type: STRING
    defaults: "kestra-io/kestra"
    description: Target GitHub repository in owner/repo format to monitor for releases.

  - id: model_name
    type: STRING
    defaults: "gemini-3.5-flash"
    description: Google Gemini model used for changelog parsing and structured risk
      evaluation (e.g., gemini-3.5-flash or gemini-2.5-flash).

  - id: force_analysis
    type: BOOL
    defaults: false
    description: When true, re-analyzes the latest release tag even if already
      recorded in KV storage.

  - id: dry_run
    type: BOOL
    defaults: true
    description: When true, audits release and simulates advisory generation without
      updating KV cursor.

tasks:
  - id: fetch_latest_release
    type: io.kestra.plugin.core.http.Request
    description: Ingests the latest published release tag and changelog from GitHub REST API
    uri: "https://api.github.com/repos/{{ inputs.repository }}/releases/latest"
    method: GET
    contentType: application/json
    headers:
      Accept: "application/vnd.github+json"
      User-Agent: "Kestra-Release-Advisor"
      Authorization: "Bearer {{ secret('GITHUB_TOKEN') }}"

  - id: check_release_seen
    type: io.kestra.plugin.core.output.OutputValues
    description: Compares latest release tag against Kestra KV store cursor to
      detect new releases
    values:
      latest_tag: "{{ outputs.fetch_latest_release.body | jq('.tag_name') | first }}"
      release_url: "{{ outputs.fetch_latest_release.body | jq('.html_url') | first }}"
      release_body: "{{ outputs.fetch_latest_release.body | jq('.body') | first ?? 'No
        changelog body provided.' }}"
      last_seen_tag: "{{ kv('release_cursor_' ~ (inputs.repository | replace('/',
        '_')), errorOnMissing=false) }}"
      is_new_release: "{{ inputs.force_analysis or (outputs.fetch_latest_release.body
        | jq('.tag_name') | first != kv('release_cursor_' ~ (inputs.repository |
        replace('/', '_')), errorOnMissing=false)) }}"

  - id: evaluate_release_status
    type: io.kestra.plugin.core.flow.If
    description: Branches execution based on whether a new unanalyzed release was detected
    condition: "{{ outputs.check_release_seen.values.is_new_release }}"
    then:
      - id: analyze_release_with_ai
        type: io.kestra.plugin.ai.completion.ChatCompletion
        description: Analyzes raw changelog text with Google Gemini to extract breaking
          changes and migration steps
        provider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
          modelName: "{{ inputs.model_name }}"
        configuration:
          temperature: 0.1
          responseFormat:
            type: JSON
            jsonSchema:
              type: object
              properties:
                has_breaking_changes:
                  type: boolean
                breaking_changes:
                  type: array
                  items:
                    type: string
                has_security_fixes:
                  type: boolean
                security_fixes:
                  type: array
                  items:
                    type: string
                actionable_migration_steps:
                  type: array
                  items:
                    type: string
                upgrade_risk_score:
                  type: integer
                  minimum: 1
                  maximum: 10
                summary:
                  type: string
              required:
                - has_breaking_changes
                - breaking_changes
                - has_security_fixes
                - security_fixes
                - actionable_migration_steps
                - upgrade_risk_score
                - summary
        messages:
          - type: SYSTEM
            content: |
              You are a Principal Software Architect evaluating open-source dependency updates for an engineering team.
              Analyze the provided changelog markdown.
              Identify any breaking changes (deprecated APIs, signature modifications, removed flags, breaking schema alterations).
              Identify security patches or CVE remediations.
              Synthesize concrete, actionable migration instructions for developers upgrading from the preceding version.
              Assign an upgrade_risk_score from 1 (trivial patch, drop-in update) to 10 (high-risk breaking migration).
              Return strictly structured JSON matching the provided schema.
          - type: USER
            content: |
              Target Repository: {{ inputs.repository }}
              Release Version: {{ outputs.check_release_seen.values.latest_tag }}
              Changelog Body:
              {{ outputs.check_release_seen.values.release_body }}

      - id: evaluate_cursor_persistence
        type: io.kestra.plugin.core.flow.If
        description: Persists release tag cursor to KV store when not running in dry-run
          simulation
        condition: "{{ not inputs.dry_run }}"
        then:
          - id: record_kv_cursor
            type: io.kestra.plugin.core.kv.Set
            description: Saves latest analyzed release tag into namespace KV storage
            key: "release_cursor_{{ inputs.repository | replace('/', '_') }}"
            value: "{{ outputs.check_release_seen.values.latest_tag }}"
            kvType: STRING

      - id: notify_slack_advisory
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatches structured release advisory card to Slack
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        messageText: |
          :package: *Upstream Release Advisory: {{ inputs.repository }} ({{ outputs.check_release_seen.values.latest_tag }})*
          *Upgrade Risk Score:* `{{ outputs.analyze_release_with_ai.jsonOutput.upgrade_risk_score }}/10`
          *Breaking Changes:* `{{ outputs.analyze_release_with_ai.jsonOutput.has_breaking_changes ? ':warning: YES' : ':white_check_mark: None' }}`
          *Security Fixes:* `{{ outputs.analyze_release_with_ai.jsonOutput.has_security_fixes ? ':shield: YES' : ':white_check_mark: None' }}`
          *Summary:* {{ outputs.analyze_release_with_ai.jsonOutput.summary }}

          *Actionable Migration Steps:*
          {% for step in outputs.analyze_release_with_ai.jsonOutput.actionable_migration_steps -%}
          • {{ step }}
          {% endfor %}
          <{{ outputs.check_release_seen.values.release_url }}|Open GitHub Release Notes>

    else:
      - id: log_up_to_date_status
        type: io.kestra.plugin.core.log.Log
        description: Records confirmation when latest release has already been analyzed
        message: "Repository {{ inputs.repository }} release {{
          outputs.check_release_seen.values.latest_tag }} is up-to-date and was
          already analyzed (last cursor: {{
          outputs.check_release_seen.values.last_seen_tag }})."

triggers:
  - id: daily_dependency_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Daily scheduled sweep of upstream dependency releases. Shipped
      disabled by default.
    cron: "0 8 * * *"
    disabled: true

  - id: github_release_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Event-driven webhook trigger to analyze releases immediately when
      GitHub dispatches a release event
    key: "{{ secret('WEBHOOK_KEY') }}"

errors:
  - id: alert_on_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alerts on-call Slack channel if release analysis encounters an
      unexpected error
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    messageText: |
      :warning: *Release Advisor FAILED on execution {{ execution.id }}*
      *Repository:* `{{ inputs.repository }}`
      Please verify GitHub API rate limits and Gemini API key permissions.