Lint Commit Messages Against Conventional Commits Before Every Release

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 }}"