id: pypi-wheel-coverage-gate
namespace: company.packaging
description: |
Check a pinned PyPI release for non-yanked wheels covering an explicit deployment
tag matrix before upgrading. Save the matching filenames and SHA256 metadata for
every target, then fail if any target has no matching wheel. No package is installed.
inputs:
- id: package
type: STRING
defaults: requests
description: PyPI distribution name, not its Python import name.
validator: '^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$'
- id: version
type: STRING
defaults: 2.32.5
description: Exact version as returned by PyPI info.version; canonical aliases
are not accepted.
validator: '^[0-9][A-Za-z0-9.!+_-]{0,63}$'
- id: targets
type: JSON
description: Each target maps to acceptable interpreter-ABI-platform tags. Any
listed tag covers that target.
defaults:
windows-arm64:
- cp312-cp312-win_arm64
- cp312-abi3-win_arm64
- py3-none-any
linux-x86_64:
- cp312-cp312-manylinux_2_17_x86_64
- cp312-abi3-manylinux_2_17_x86_64
- py3-none-any
- id: worker_os
type: SELECT
values:
- LINUX
- WINDOWS
defaults: LINUX
description: Operating system of the Kestra worker running Node.js, independent
of the wheel targets.
tasks:
- id: fetch_release
type: io.kestra.plugin.core.http.Request
description: Read only the selected release's public metadata from PyPI.
uri: "https://pypi.org/pypi/{{ inputs.package }}/{{ inputs.version }}/json"
method: GET
headers:
Accept: application/json
options:
followRedirects: false
- id: assess_coverage
type: io.kestra.plugin.scripts.node.Script
description: Match compressed wheel tags against the explicit matrix and
preserve the full coverage evidence.
taskRunner:
type: io.kestra.plugin.core.runner.Process
targetOS: "{{ inputs.worker_os }}"
interpreter: "{{ inputs.worker_os == 'WINDOWS' ? ['powershell.exe',
'-NoProfile', '-Command'] : ['/bin/sh', '-c'] }}"
env:
PACKAGE: "{{ inputs.package }}"
VERSION: "{{ inputs.version }}"
TARGETS: "{{ inputs.targets | toJson }}"
inputFiles:
release.json: "{{ outputs.fetch_release.body }}"
outputFiles:
- wheel-coverage.json
script: |
const fs = require('node:fs');
const path = require('node:path');
const normalize = value => value.toLowerCase().replace(/[-_.]+/g, '-');
const tagPattern = /^[A-Za-z0-9_]+-[A-Za-z0-9_]+-[A-Za-z0-9_]+$/;
function targetsFrom(value) {
if (!value || Array.isArray(value) || typeof value !== 'object') {
throw Error('targets must be a JSON object mapping target names to tag arrays');
}
const entries = Object.entries(value);
if (!entries.length || entries.length > 32) throw Error('Specify 1 to 32 targets');
for (const [name, tags] of entries) {
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(name)) throw Error('Invalid target name');
if (!Array.isArray(tags) || !tags.length || tags.length > 256 ||
tags.some(tag => typeof tag !== 'string' || tag.length > 200 || !tagPattern.test(tag))) {
throw Error('Each target needs 1 to 256 explicit interpreter-ABI-platform tags');
}
}
return entries;
}
function wheelTags(filename) {
if (typeof filename !== 'string' || !filename.endsWith('.whl')) return null;
const parts = filename.slice(0, -4).split('-');
if (parts.length !== 5 && parts.length !== 6) return null;
if (parts.length === 6 && !/^[0-9][A-Za-z0-9_]*$/.test(parts[2])) return null;
const tags = parts.slice(-3);
if (tags.some(tag => !/^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*$/.test(tag))) return null;
return {distribution: parts[0], version: parts[1], groups: tags.map(tag => new Set(tag.split('.')))};
}
function assess(release, packageName, version, targets) {
const entries = targetsFrom(targets);
if (!release || !release.info || typeof release.info.name !== 'string' ||
normalize(release.info.name) !== normalize(packageName) || release.info.version !== version ||
!Array.isArray(release.urls)) throw Error('Unexpected PyPI release identity or metadata shape');
const usable = [];
const excluded = [];
for (const file of release.urls) {
if (!file || file.packagetype !== 'bdist_wheel') continue;
const parsed = wheelTags(file.filename);
let reason;
if (file.yanked !== false) reason = 'yanked or missing yanked status';
else if (!parsed || normalize(parsed.distribution) !== normalize(packageName) || parsed.version !== version) reason = 'invalid wheel filename';
else if (!file.digests || !/^[a-f0-9]{64}$/i.test(file.digests.sha256 || '')) reason = 'missing SHA256 metadata';
if (reason) excluded.push({filename: file.filename || null, reason});
else usable.push({file, parsed});
}
const coverage = entries.map(([target, tags]) => {
const matches = usable.filter(({parsed}) => tags.some(tag =>
tag.split('-').every((part, index) => parsed.groups[index].has(part))));
return {
target, accepted_tags: tags, covered: matches.length > 0,
wheels: matches.map(({file}) => ({
filename: file.filename, sha256: file.digests.sha256,
requires_python: file.requires_python || null
})).sort((a, b) => a.filename.localeCompare(b.filename))
};
});
const missing = coverage.filter(row => !row.covered).map(row => row.target);
return {
schema: 'pypi-wheel-coverage/1', package: release.info.name, version,
status: missing.length ? 'BLOCK' : 'PASS', missing_targets: missing,
usable_wheels: usable.length, excluded_wheels: excluded, coverage,
scope: 'Published wheel-tag coverage only; Requires-Python and dependency resolution are not evaluated.'
};
}
function main() {
if (!process.env.WORKING_DIR) throw Error('Kestra working directory is not set');
const release = JSON.parse(fs.readFileSync(path.join(process.env.WORKING_DIR, 'release.json'), 'utf8'));
const report = assess(release, process.env.PACKAGE, process.env.VERSION, JSON.parse(process.env.TARGETS));
fs.writeFileSync(path.join(process.env.WORKING_DIR, 'wheel-coverage.json'), JSON.stringify(report, null, 2));
console.log('::' + JSON.stringify({outputs: {
status: report.status, missing_count: report.missing_targets.length,
target_count: report.coverage.length, usable_wheels: report.usable_wheels
}}) + '::');
console.log('PyPI wheel coverage: ' + report.status);
}
module.exports = {assess, targetsFrom, wheelTags};
if (require.main === module) main();
- id: publish_report
type: io.kestra.plugin.core.output.OutputValues
description: Expose evidence before a failed gate stops the execution.
values:
status: "{{ outputs.assess_coverage.vars.status }}"
missing_count: "{{ outputs.assess_coverage.vars.missing_count }}"
report_uri: "{{ outputs.assess_coverage.outputFiles['wheel-coverage.json'] }}"
- id: coverage_gate
type: io.kestra.plugin.core.flow.If
condition: "{{ outputs.assess_coverage.vars.status == 'BLOCK' }}"
then:
- id: stop_upgrade
type: io.kestra.plugin.core.execution.Fail
errorMessage: Required PyPI wheels are missing. Review wheel-coverage.json
before upgrading.
else:
- id: log_verdict
type: io.kestra.plugin.core.log.Log
message: "Wheel coverage {{ outputs.assess_coverage.vars.status }}; missing
targets {{ outputs.assess_coverage.vars.missing_count }}. See the
report for filenames."
triggers:
- id: github_pull_request
type: io.kestra.plugin.core.trigger.Webhook
description: Run the wheel gate when GitHub opens, reopens, or updates a pull request.
key: "{{ secret('PYPI_UPGRADE_WEBHOOK_KEY') }}"
when: "{{ trigger.body.pull_request is defined and trigger.body.action in
['opened', 'reopened', 'synchronize'] }}"