id: pypi-dependency-release-health-watch
namespace: company.team
description: |
Audits the Python dependencies declared in a requirements.txt file against the official PyPI registry.
It checks whether pinned package versions are yanked, outdated, or have had no updates for a long time (stale),
and sends a Slack alert only when new issues are detected.
inputs:
- id: requirements_url
type: STRING
description: Raw HTTPS URL of the requirements.txt file to inspect. Works for
any public repository on GitHub, GitLab, etc.
defaults: https://raw.githubusercontent.com/encode/httpx/master/requirements.txt
- id: max_packages
type: INT
description: Maximum number of packages to audit in a single execution.
defaults: 25
- id: outdated_threshold
type: SELECT
description: Minimum version lag required to mark a dependency as OUTDATED.
Selecting major checks only for major version differences (or minor for
0.x packages).
values:
- major
- minor
- patch
defaults: major
- id: stale_after_days
type: INT
description: A package is flagged as STALE if its latest release is older than
this many days.
defaults: 365
triggers:
- id: weekly
type: io.kestra.plugin.core.trigger.Schedule
description: Run every Monday at 08:00 UTC. Disabled by default until you
configure the Slack incoming webhook.
cron: "0 8 * * 1"
disabled: true
tasks:
- id: fetch_requirements
type: io.kestra.plugin.core.http.Request
description: Download the requirements.txt file from the specified URL.
uri: "{{ inputs.requirements_url }}"
method: GET
- id: list_packages
type: io.kestra.plugin.transform.jsonata.TransformValue
description: Parse dependencies from requirements.txt, filter out comments,
editable flags, and non-package lines, strip optional extras, and limit to
max_packages.
from: "{{ outputs.fetch_requirements.body }}"
expression: |
(
$lines := $split($, "\n");
$clean := $lines[$not($contains($, /^[ \t]*(#|-|$)/)) and $contains($, /[a-zA-Z0-9]/)];
$parsed := $clean.{
"name": $replace($, /^[ \t]*([a-zA-Z0-9_.-]+)(\[[^\]]*\])?.*$/, "$1"),
"pinned": $contains($, /[=><~^!]+[ \t]*[0-9]/) ? $replace($, /^.*?[=><~^!]+[ \t]*([0-9][0-9a-zA-Z_.-]*).*$/, "$1") : "latest"
};
$parsed[[0..{{ inputs.max_packages }} - 1]]
)
- id: check_packages
type: io.kestra.plugin.core.flow.Loop
description: Query the PyPI registry for each package and assess release health
against the pinned version.
values: "{{ outputs.list_packages.value | toJson }}"
concurrencyLimit: 2
outputs:
- id: verdict
type: JSON
value: "{{ outputs.assess_health.value }}"
tasks:
- id: fetch_pypi_metadata
type: io.kestra.plugin.core.http.Request
description: Query the official PyPI JSON API for package metadata and release
history.
uri: "https://pypi.org/pypi/{{ item.value.name }}/json"
method: GET
headers:
Accept: "application/json"
retry:
type: constant
interval: PT3S
maxAttempts: 3
- id: assess_health
type: io.kestra.plugin.transform.jsonata.TransformValue
description: Assess whether the pinned version is yanked, outdated, or stale.
from: "{{ outputs.fetch_pypi_metadata.body }}"
expression: |
(
$pinned := "{{ item.value.pinned }}";
$latest := info.version;
$pinnedFiles := $lookup(releases, $pinned);
$isYanked := $boolean($pinnedFiles[0].yanked);
$latestFiles := $lookup(releases, $latest);
$releaseTime := $latestFiles[0].upload_time_iso_8601;
$age := $releaseTime ? ($toMillis($now()) - $toMillis($releaseTime)) / 86400000 : 0;
$p := $split($pinned, ".");
$l := $split($latest, ".");
$behind := (
($number($l[0]) > $number($p[0]) or ($p[0] = "0" and $l[0] = "0" and $number($l[1]) > $number($p[1]))) ? 3
: ($number($l[0]) = $number($p[0]) and $number($l[1]) > $number($p[1])) ? 2
: ($pinned != $latest and $pinned != "latest") ? 1
: 0
);
$needed := {"major": 3, "minor": 2, "patch": 1}."{{ inputs.outdated_threshold }}";
$status := $isYanked ? "YANKED"
: ($count($pinnedFiles) = 0 and $pinned != "latest" and $pinned != $latest) ? "UNKNOWN_VERSION"
: $age > {{ inputs.stale_after_days }} ? "STALE"
: $behind >= $needed ? "OUTDATED"
: "OK";
{
"package": info.name,
"pinned": $pinned,
"latest": $latest,
"status": $status,
"isYanked": $isYanked,
"latestAgeDays": $round($age),
"requiresAttention": $status != "OK"
}
)
- id: pause_for_rate_limit
type: io.kestra.plugin.core.flow.Pause
description: Pause briefly between package lookups to respect PyPI registry rate
limits.
pauseDuration: PT0.5S
- id: summarize
type: io.kestra.plugin.transform.jsonata.TransformValue
description: Aggregate verdicts into a health digest with counts and actionable items.
from: "{{ outputs.check_packages.verdict | default([]) | toJson }}"
expression: |
(
$reports := $;
$issues := $reports[requiresAttention = true];
$counts := {
"total": $count($reports),
"yanked": $count($reports[status = "YANKED"]),
"outdated": $count($reports[status = "OUTDATED"]),
"stale": $count($reports[status = "STALE"]),
"unknown": $count($reports[status = "UNKNOWN_VERSION"]),
"ok": $count($reports[status = "OK"])
};
{
"counts": $counts,
"issues": $issues,
"hasIssues": $count($issues) > 0,
"digest": $issues.{
"package": package,
"pinned": pinned,
"latest": latest,
"status": status,
"latestAgeDays": latestAgeDays
}
}
)
- id: previous_report
type: io.kestra.plugin.core.kv.Get
description: Retrieve the previous health digest from Kestra's KV store.
key: "pypi_report_{{ inputs.requirements_url | slugify }}"
errorOnMissing: false
- id: alert_if_new
type: io.kestra.plugin.core.flow.If
description: Send a Slack alert only if issues exist and the digest has changed
since the last execution.
condition: "{{ outputs.summarize.value.hasIssues and
(outputs.previous_report.value != (outputs.summarize.value.digest |
toJson)) }}"
then:
- id: send_slack_alert
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post the Python dependency health summary to Slack.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "🐍 *Python Dependency Health Alert (PyPI)*",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "🐍 Python Dependency Health Alert",
"emoji": true
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Manifest:* `{{ inputs.requirements_url }}`\n*Total audited:* {{ outputs.summarize.value.counts.total }} | *Issues found:* {{ outputs.summarize.value.counts.total - outputs.summarize.value.counts.ok }}\n• Yanked: {{ outputs.summarize.value.counts.yanked }} | Outdated: {{ outputs.summarize.value.counts.outdated }} | Stale: {{ outputs.summarize.value.counts.stale }}"
}
},
{
"type": "divider"
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Actionable Packages:*\n{% for item in outputs.summarize.value.digest %}• *{{ item.package }}*: pinned `{{ item.pinned }}` → latest `{{ item.latest }}` [{{ item.status }}]{% if item.latestAgeDays > 0 %} (latest release {{ item.latestAgeDays }}d ago){% endif %}\n{% endfor %}"
}
}
]
}
- id: remember_report
type: io.kestra.plugin.core.kv.Set
description: Store the current digest in KV to prevent redundant alerts on
subsequent executions.
key: "pypi_report_{{ inputs.requirements_url | slugify }}"
value: "{{ outputs.summarize.value.digest | toJson }}"
errors:
- id: alert_on_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Notify Slack when the dependency audit workflow encounters an
unhandled execution error.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "⚠️ *PyPI Dependency Health Watch Failed*\nFlow `{{ flow.id }}` in namespace `{{ flow.namespace }}` failed execution `{{ execution.id }}` while fetching `{{ inputs.requirements_url }}`."
}