id: gitea-repository-branch-hygiene-and-drift-sentinel
namespace: company.devops
description: |
GitOps hygiene sentinel that audits self-hosted Gitea repositories for stale abandoned
feature branches and unreviewed pull request backlogs, classifies repository drift
through a Switch gate, dispatches actionable Slack cleanup alerts, and exports
structured telemetry for engineering velocity audits.
inputs:
- id: gitea_url
type: STRING
displayName: "Gitea Server URL"
defaults: "http://localhost:3000"
description: "Base URL for the Gitea instance without trailing slash (e.g.,
http://gitea.internal:3000)."
- id: repo_owner
type: STRING
displayName: "Repository Owner / Organization"
defaults: "engineering"
description: "Organization name or username owning the target Gitea repository."
- id: repo_name
type: STRING
displayName: "Repository Name"
defaults: "core-service"
description: "Target repository slug to audit for branch staleness and PR backlogs."
- id: stale_days_threshold
type: INT
displayName: "Stale Branch Age Threshold (Days)"
defaults: 30
description: "Inactivity horizon in days beyond which unmerged non-protected
branches are flagged as stale."
- id: max_stale_branches
type: INT
displayName: "Max Tolerable Stale Branches"
defaults: 5
description: "Maximum allowable stale branches before escalating repository
hygiene alerts."
- id: slack_channel
type: STRING
displayName: "Slack Alert Channel"
defaults: "#dev-ops"
description: "Target Slack channel for Gitea repository hygiene digests and
cleanup alerts."
triggers:
- id: scheduled_hygiene_audit
type: io.kestra.plugin.core.trigger.Schedule
description: "Triggers weekly repository hygiene scan every Monday at 08:00 UTC.
Shipped disabled by default for initial connection verification."
cron: "0 8 * * 1"
disabled: true
tasks:
- id: probe_branches
type: io.kestra.plugin.core.http.Request
description: "Retrieves active branches, latest commit timestamps, and
protection metadata from Gitea REST API."
uri: "{{ inputs.gitea_url }}/api/v1/repos/{{ inputs.repo_owner }}/{{
inputs.repo_name }}/branches"
method: GET
headers:
Authorization: "token {{ secret('GITEA_API_TOKEN') }}"
Accept: "application/json"
options:
allowFailed: false
- id: probe_pull_requests
type: io.kestra.plugin.core.http.Request
description: "Fetches active open pull requests from Gitea to assess review
backlog and unresolved integration merges."
uri: "{{ inputs.gitea_url }}/api/v1/repos/{{ inputs.repo_owner }}/{{
inputs.repo_name }}/pulls?state=open"
method: GET
headers:
Authorization: "token {{ secret('GITEA_API_TOKEN') }}"
Accept: "application/json"
options:
allowFailed: false
- id: evaluate_branch_staleness
type: io.kestra.plugin.scripts.python.Script
description: "Parses branch commit timestamps against current UTC date,
identifies abandoned branches, and classifies drift status."
containerImage: python:3.11-slim
taskRunner:
type: io.kestra.plugin.scripts.runner.docker.Docker
beforeCommands:
- pip install kestra
env:
BRANCHES_JSON: "{{ outputs.probe_branches.body }}"
PULLS_JSON: "{{ outputs.probe_pull_requests.body }}"
STALE_THRESHOLD_DAYS: "{{ inputs.stale_days_threshold }}"
MAX_STALE_LIMIT: "{{ inputs.max_stale_branches }}"
script: |
import os
import sys
import json
import datetime
from kestra import Kestra
branches_data = json.loads(os.environ.get("BRANCHES_JSON", "[]"))
pulls_data = json.loads(os.environ.get("PULLS_JSON", "[]"))
stale_threshold = int(os.environ.get("STALE_THRESHOLD_DAYS", 30))
max_stale = int(os.environ.get("MAX_STALE_LIMIT", 5))
now = datetime.datetime.now(datetime.timezone.utc)
protected_names = {"main", "master", "develop", "dev", "production", "staging"}
stale_branches = []
oldest_branch = None
max_age_days = 0
for b in branches_data:
name = b.get("name", "")
is_protected = b.get("protected", False) or (name.lower() in protected_names)
if is_protected:
continue
commit = b.get("commit", {})
ts_str = commit.get("timestamp") or commit.get("created")
if not ts_str:
continue
try:
commit_dt = datetime.datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
age_days = (now - commit_dt).days
if age_days >= stale_threshold:
stale_branches.append({
"name": name,
"age_days": age_days,
"last_commit": ts_str
})
if age_days > max_age_days:
max_age_days = age_days
oldest_branch = name
except Exception:
pass
stale_count = len(stale_branches)
open_prs = len(pulls_data)
status = "HYGIENIC"
if stale_count >= max_stale:
status = "STALE_BRANCHES_DETECTED"
elif open_prs >= 10:
status = "OPEN_PR_BACKLOG"
stale_names_sample = [sb["name"] for sb in sorted(stale_branches, key=lambda x: -x["age_days"])[:5]]
Kestra.outputs({
"total_branches": len(branches_data),
"stale_branches_count": stale_count,
"stale_branch_names": stale_names_sample,
"oldest_branch_name": oldest_branch or "none",
"oldest_branch_days": max_age_days,
"open_prs_count": open_prs,
"status": status
})
- id: classify_repository_health
type: io.kestra.plugin.core.flow.Switch
description: "Routes workflow into stale branch escalation, PR backlog
notification, or hygienic status branches."
value: "{{ outputs.evaluate_branch_staleness.vars.status }}"
cases:
STALE_BRANCHES_DETECTED:
- id: notify_stale_branches
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: "Dispatches repository hygiene alert card with stale branch
inventory and cleanup guidance."
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"channel": "{{ inputs.slack_channel }}",
"text": ":warning: *GITEA HYGIENE ALERT: Stale Branches Exceeded Threshold*",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "GITEA ALERT: Stale Branch Accumulation",
"emoji": true
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Repository:*\n`{{ inputs.repo_owner }}/{{ inputs.repo_name }}`"
},
{
"type": "mrkdwn",
"text": "*Status:*\n:wastebasket: `ACTION REQUIRED`"
},
{
"type": "mrkdwn",
"text": "*Stale Branches / Limit:*\n`{{ outputs.evaluate_branch_staleness.vars.stale_branches_count }}` (Limit: `{{ inputs.max_stale_branches }}`)"
},
{
"type": "mrkdwn",
"text": "*Oldest Abandoned Branch:*\n`{{ outputs.evaluate_branch_staleness.vars.oldest_branch_name }}` (`{{ outputs.evaluate_branch_staleness.vars.oldest_branch_days }} days old`)"
},
{
"type": "mrkdwn",
"text": "*Open Pull Requests:*\n`{{ outputs.evaluate_branch_staleness.vars.open_prs_count }}`"
},
{
"type": "mrkdwn",
"text": "*Execution ID:*\n`{{ execution.id }}`"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Recommended Remediation:*\nReview abandoned feature branches and prune merged refs using `git push origin --delete <branch>` or configure Gitea automated branch deletion upon PR merge."
}
}
]
}
- id: log_stale_warning
type: io.kestra.plugin.core.log.Log
description: "Logs stale branch hygiene breach in Kestra execution history."
message: "GITEA WARNING: Repository {{ inputs.repo_owner }}/{{ inputs.repo_name
}} has {{
outputs.evaluate_branch_staleness.vars.stale_branches_count }} stale
branches (limit {{ inputs.max_stale_branches }}). Oldest branch: {{
outputs.evaluate_branch_staleness.vars.oldest_branch_name }} ({{
outputs.evaluate_branch_staleness.vars.oldest_branch_days }} days
inactive)."
OPEN_PR_BACKLOG:
- id: notify_pr_backlog
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: "Dispatches advisory alert when unmerged pull requests accumulate
beyond review velocity thresholds."
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"channel": "{{ inputs.slack_channel }}",
"text": ":clipboard: *GITEA ADVISORY: Elevated Pull Request Review Backlog*",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "GITEA ADVISORY: Pull Request Review Backlog",
"emoji": true
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Repository:*\n`{{ inputs.repo_owner }}/{{ inputs.repo_name }}`"
},
{
"type": "mrkdwn",
"text": "*Open PRs:*\n`{{ outputs.evaluate_branch_staleness.vars.open_prs_count }}`"
}
]
}
]
}
- id: log_pr_warning
type: io.kestra.plugin.core.log.Log
description: "Logs pull request backlog advisory in execution history."
message: "GITEA ADVISORY: Repository {{ inputs.repo_owner }}/{{ inputs.repo_name
}} has {{ outputs.evaluate_branch_staleness.vars.open_prs_count }}
open pull requests awaiting review."
HYGIENIC:
- id: log_hygienic_repo
type: io.kestra.plugin.core.log.Log
description: "Records clean repository state when stale branches remain within
acceptable limits."
message: "GITEA HYGIENIC: Repository {{ inputs.repo_owner }}/{{ inputs.repo_name
}} is healthy. {{
outputs.evaluate_branch_staleness.vars.stale_branches_count }} stale
branches (below limit {{ inputs.max_stale_branches }}), {{
outputs.evaluate_branch_staleness.vars.open_prs_count }} open PRs."
- id: finalize_repository_audit
type: io.kestra.plugin.core.output.OutputValues
description: "Publishes structured repository hygiene metrics for engineering
velocity dashboards and audit records."
values:
execution_id: "{{ execution.id }}"
repository: "{{ inputs.repo_owner }}/{{ inputs.repo_name }}"
total_branches: "{{ outputs.evaluate_branch_staleness.vars.total_branches }}"
stale_branches_count: "{{ outputs.evaluate_branch_staleness.vars.stale_branches_count }}"
oldest_branch_name: "{{ outputs.evaluate_branch_staleness.vars.oldest_branch_name }}"
oldest_branch_days: "{{ outputs.evaluate_branch_staleness.vars.oldest_branch_days }}"
open_prs_count: "{{ outputs.evaluate_branch_staleness.vars.open_prs_count }}"
classification: "{{ outputs.classify_repository_health.value }}"
errors:
- id: notify_gitea_outage
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: "Alerts DevOps team if Gitea API is unreachable or authentication
token expires."
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"channel": "{{ inputs.slack_channel }}",
"text": ":rotating_light: *GITEA HYGIENE SENTINEL PROBE FAILED*\n*Target:* `{{ inputs.gitea_url }}`\n*Repository:* `{{ inputs.repo_owner }}/{{ inputs.repo_name }}`\n*Failure:* Sentinel was unable to connect to Gitea API or token authentication failed.\n*Execution ID:* `{{ execution.id }}`"
}