id: conventional-commits-enforcer
namespace: company.team
description: |
Enforce the Conventional Commits format on the most recent history of a
repository so automated release tooling can always derive the next version.
A push webhook starts the run, a containerized git step collects the last ten
commit subjects into commits.txt, and a python step classifies every subject
with the specification regex plus breaking change detection. Non-compliant
history escalates into a GitHub issue, a Slack alert and a per-violation
remediation file, while clean history exits green, and the execution exposes
the verdict, the violation count, the violations array and the breaking flag.
triggers:
- id: on_push
type: io.kestra.plugin.core.trigger.Webhook
description: CI POSTs here after every push so the newest subjects are linted
while the change is still open.
key: "{{ secret('COMMIT_LINT_WEBHOOK_KEY') }}"
- id: daily_recheck
type: io.kestra.plugin.core.trigger.Schedule
description: Disabled net that would recheck the last day of history each
morning once someone switches it on.
cron: "0 6 * * *"
disabled: true
inputs:
- id: repository
type: STRING
defaults: acme/platform-api
description: Repository in owner/name form that the checked commits belong to.
- id: branch
type: STRING
defaults: main
description: Branch whose most recent subjects are being linted.
- id: commit_limit
type: INT
defaults: 10
description: How many subjects the git step tries to collect when a checkout is
available.
tasks:
# --- 1. collect and validate ---
- id: workspace
type: io.kestra.plugin.core.flow.WorkingDirectory
description: One shared directory so the git collector, the python validator and
the remediation report all see the same files.
tasks:
- id: collect_commits
type: io.kestra.plugin.scripts.shell.Commands
description: Fetch the last ten subjects with git log inside the alpine/git
container, best effort, and fall back to a built-in fixture when no
checkout exists.
taskRunner:
type: io.kestra.plugin.scripts.runner.docker.Docker
containerImage: alpine/git:2.47.2
commands:
- |
git log -n {{ inputs.commit_limit }} --format='%H %s' > commits.txt 2>/dev/null || true
if [ ! -s commits.txt ]; then
cat > commits.txt <<'COMMITS_EOF'
0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c feat(api): add endpoint
1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d fix: correct invoice rounding
2b3c4d5e6f708192a3b4c5d6e7f809123b3c4d5e docs: update deployment runbook
3c4d5e6f708192a3b4c5d6e7f809123c4d5e6f70 chore(deps): bump alpine git image
4d5e6f708192a3b4c5d6e7f8091234d5e6f7081 refactor(db)!: replace connection pool
5e6f708192a3b4c5d6e7f80912345e6f708192a3 perf: cache schema lookups
6f708192a3b4c5d6e7f809123456f708192a3b4 fixed stuff
708192a3b4c5d6e7f809123456708192a3b4c5d Added tests for login flow
8192a3b4c5d6e7f80912345678192a3b4c5d6e7 feature: add shiny button
92a3b4c5d6e7f8091234567892a3b4c5d6e7f80 feat missing colon separator
COMMITS_EOF
fi
echo "commits.txt now holds $(wc -l < commits.txt) subjects"
- id: validate_commits
type: io.kestra.plugin.scripts.python.Script
description: Match every subject against the Conventional Commits pattern, flag
breaking changes, and emit violations, valid_count and breaking for
the gate below.
taskRunner:
type: io.kestra.plugin.core.runner.Process
script: |
import json
import os
import re
ALLOWED = ("feat", "fix", "docs", "style", "refactor", "perf", "test",
"build", "ci", "chore", "revert")
PATTERN = re.compile(
r"^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)"
r"(\([a-z0-9 .-]+\))?!?: .{1,80}$"
)
TYPE_PREFIX = re.compile(r"^([a-z]+)")
BAD_SCOPE = re.compile(r"^[a-z]+\(")
SCOPE_OK = re.compile(r"^[a-z]+\([a-z0-9 .-]+\)")
STRUCTURE = re.compile(r"^[a-z]+(\([a-z0-9 .-]+\))?!?: ")
subjects = []
if os.path.exists("commits.txt"):
with open("commits.txt", "r", encoding="utf-8") as handle:
subjects = [line.strip() for line in handle if line.strip()]
violations = []
valid_count = 0
breaking = False
if not subjects:
violations.append({
"sha": "",
"subject": "",
"reason": "commits.txt held no subjects, so nothing could be checked",
})
for line in subjects:
fields = line.split(None, 1)
if len(fields) != 2:
violations.append({
"sha": (fields[0] if fields else "")[:40],
"subject": line,
"reason": "expected a sha and a subject separated by whitespace",
})
continue
sha, subject = fields
if PATTERN.match(subject):
valid_count += 1
if subject.split(":", 1)[0].endswith("!") or "BREAKING CHANGE" in subject:
breaking = True
continue
if "BREAKING CHANGE" in subject:
breaking = True
found = TYPE_PREFIX.match(subject)
if found is None or found.group(1) not in ALLOWED:
reason = ("type must be one of feat, fix, docs, style, refactor, "
"perf, test, build, ci, chore, revert")
elif BAD_SCOPE.match(subject) and not SCOPE_OK.match(subject):
reason = ("scope inside the parentheses may only hold lowercase letters, "
"digits, spaces, dots and hyphens")
elif not STRUCTURE.match(subject):
reason = "missing ': ' separator after the type and the optional scope"
else:
reason = "description after the colon must be between 1 and 80 characters"
violations.append({"sha": sha, "subject": subject, "reason": reason})
print("::" + json.dumps(
{"outputs": {"violations": violations, "valid_count": valid_count, "breaking": breaking}},
ensure_ascii=True,
) + "::")
# --- 2. gate and escalate ---
- id: check_violations
type: io.kestra.plugin.core.flow.If
description: Route the run on whether any subject failed the pattern, so
escalation only fires when there is something to rewrite.
condition: "{{ (outputs.validate_commits.vars.violations | length) > 0 }}"
then:
- id: write_remediation_report
type: io.kestra.plugin.core.flow.Loop
description: Append one rewrite instruction per violation so report.txt can be
handed straight to the commit author.
values: "{{ outputs.validate_commits.vars.violations }}"
concurrencyLimit: 1
tasks:
- id: append_remediation_line
type: io.kestra.plugin.scripts.shell.Commands
description: Print a single remediation line for the violation currently in
scope.
commands:
- |
printf '%s\n' "rewrite {{ item.value.sha }} {{ item.value.subject }} -- {{ item.value.reason }}" >> report.txt
- id: open_violation_issue
type: io.kestra.plugin.github.issues.Create
description: Open an issue carrying the full violation list so the rewrite lands
in the backlog engineers already watch.
oauthToken: "{{ secret('GITHUB_TOKEN') }}"
repository: "{{ inputs.repository }}"
title: "Conventional Commits violations in {{ inputs.repository }} ({{
(outputs.validate_commits.vars.violations | length) }} found)"
body: |
## Conventional Commits violations
{{ (outputs.validate_commits.vars.violations | length) }} of the last {{ inputs.commit_limit }} subjects on `{{ inputs.branch }}` in `{{ inputs.repository }}` do not follow the pattern, so the next version cannot be derived automatically.
{% for v in outputs.validate_commits.vars.violations %}- `{{ v.sha | slice(0, 7) }}` {{ v.subject }} ({{ v.reason }})
{% endfor %}
Breaking change flagged, so the next release is a major one. {{ outputs.validate_commits.vars.breaking }}
Reword each subject above to `type(scope): description`, push the fix, and close this issue. Execution {{ execution.id }}.
labels:
- conventional-commits
- release-blocker
- id: alert_slack
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post the violation count and the breaking flag so the team hears
about the block before the release job does.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "Conventional Commits lint failed for {{ inputs.repository }}@{{ inputs.branch }}. {{ (outputs.validate_commits.vars.violations | length) }} of the last {{ inputs.commit_limit }} subjects are non-compliant, breaking change flagged, {{ outputs.validate_commits.vars.breaking }}. An issue lists every violation and report.txt holds one rewrite line per commit. Execution {{ execution.id }}."
}
else:
- id: record_compliant
type: io.kestra.plugin.scripts.shell.Commands
description: Write the all-clear into report.txt so a clean run still leaves the
same artifact behind.
commands:
- |
printf '%s\n' "COMPLIANT 0 violations in the last {{ inputs.commit_limit }} subjects of {{ inputs.repository }}@{{ inputs.branch }}" > report.txt
errors:
- id: notify_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Escalate any failure to the ops channel with the execution url.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{"text": "FAILED: {{ flow.id }} {{ execution.id }}"}
outputs:
- id: verdict
type: STRING
value: "{{ (outputs.validate_commits.vars.violations | length) > 0 ?
'NON_COMPLIANT' : 'COMPLIANT' }}"
- id: violation_count
type: INT
value: "{{ outputs.validate_commits.vars.violations | length }}"
- id: violations
type: ARRAY
value: "{{ outputs.validate_commits.vars.violations | toJson }}"
- id: breaking
type: BOOL
value: "{{ outputs.validate_commits.vars.breaking }}"