Schedule icon
Request icon
Script icon
Docker icon
Switch icon
SlackIncomingWebhook icon
Log icon
OutputValues icon

Gitea Repository Branch Hygiene & Drift Sentinel

Audits Gitea self-hosted repositories for stale abandoned branches and pull request backlogs, dispatching automated Slack hygiene alerts and audit logs.

Categories
Infrastructure

Self-hosted Gitea instances power private source control, air-gapped CI/CD pipelines, and internal developer platforms. As development velocity scales across engineering teams, hundreds of short-lived feature and experimental branches are created and frequently abandoned post-merge. Unpruned repositories bloat clone payload sizes, slow down Git search operations, trigger redundant webhook workflows, and obscure active release paths.

This blueprint provides an automated GitOps hygiene sentinel that audits target Gitea repositories on a scheduled cadence. It queries active branches and open pull requests via the Gitea REST API, measures commit inactivity against configurable staleness thresholds, evaluates repository drift through a stateful Switch gate, dispatches actionable Slack cleanup alerts, and exports telemetry for developer velocity tracking.

How it works

  1. scheduled_hygiene_audit (io.kestra.plugin.core.trigger.Schedule) triggers automated repository surveillance weekly (e.g. Monday mornings). Shipped disabled by default so teams can verify initial API credentials manually.
  2. probe_branches (io.kestra.plugin.core.http.Request) invokes the Gitea REST endpoint GET /api/v1/repos/{owner}/{repo}/branches using personal access token authentication to retrieve branch names, commit metadata, and branch protection flags.
  3. probe_pull_requests (io.kestra.plugin.core.http.Request) fetches active open pull requests from GET /api/v1/repos/{owner}/{repo}/pulls?state=open to assess review backlogs.
  4. evaluate_branch_staleness (io.kestra.plugin.scripts.python.Script running inside Docker) parses ISO commit timestamps against current UTC dates, filters out protected branches (main, master, develop, etc.), identifies branches exceeding stale_days_threshold (default 30 days), and classifies repository status.
  5. classify_repository_health (io.kestra.plugin.core.flow.Switch) evaluates the classification outcome:
    • STALE_BRANCHES_DETECTED: Triggered when stale branches exceed max_stale_branches. Dispatches an alert card to #dev-ops via io.kestra.plugin.slack.notifications.SlackIncomingWebhook listing oldest abandoned branches and cleanup guidance.
    • OPEN_PR_BACKLOG: Triggered when open PRs accumulate beyond review thresholds. Sends a reminder to prevent stale merge conflicts.
    • HYGIENIC: Records clean repository state via io.kestra.plugin.core.log.Log.
  6. finalize_repository_audit (io.kestra.plugin.core.output.OutputValues) publishes clean audit telemetry for engineering metrics and compliance dashboards.
  7. The global errors handler captures connection failures or token expiration to alert DevOps administrators out-of-band.

What you get

  • Automated detection of abandoned Git branches before repository clutter impacts CI/CD clone performance.
  • Visibility into open pull request review backlogs to improve team delivery velocity.
  • Contextual Slack alerts detailing stale branch counts, oldest branch names, and inactivity duration in days.
  • Centralized execution history and structured repository telemetry in Kestra.

Who it's for

  • Platform Engineers and DevOps leads maintaining self-hosted Gitea infrastructure.
  • Engineering Managers tracking developer velocity, code hygiene, and pull request turnaround times.
  • Release Engineers safeguarding Git repository performance across internal development teams.

Why orchestrate this with Kestra

Repository maintenance requires recurring scheduling, containerized script execution, secure credential masking, conditional branching, and enterprise messaging integration. Standalone cron scripts lack centralized audit logging, secret isolation, and error alerting when credentials expire. Kestra delivers a declarative YAML workflow with built-in secret masking, execution tracking, and seamless Slack collaboration.

Prerequisites

  • A running Gitea instance (version 1.18+), reachable over HTTP or HTTPS. Gitea provides an official open-source Docker image (gitea/gitea:latest) requiring no commercial license.
  • A Gitea personal access token generated under User Settings > Applications with read:repository scope.
  • An incoming Slack webhook configured for operational notifications.
  • Docker enabled on Kestra workers to execute the Python evaluation container.

Secrets

  • GITEA_API_TOKEN: Personal access token with read access to repository branches and pull requests.
  • SLACK_WEBHOOK_URL: Slack Incoming Webhook URL used to dispatch operational hygiene digests.

Quick start

  1. Start a local Gitea container:
    docker run -d --name gitea-sentinel -p 3000:3000 -v gitea-data:/data gitea/gitea:latest
    
  2. Log into Gitea (http://localhost:3000), generate an API token under Settings > Applications, and create a target repository with sample feature branches.
  3. Configure GITEA_API_TOKEN and SLACK_WEBHOOK_URL in your Kestra namespace secrets.
  4. Import this blueprint into Kestra under namespace company.devops.
  5. Click Execute with your target repo_owner and repo_name to observe branch evaluation and telemetry outputs.
  6. Enable scheduled_hygiene_audit to activate recurring weekly repository surveillance.

How to extend

  • Add automated branch pruning: invoke DELETE /api/v1/repos/{owner}/{repo}/branches/{branch} to delete abandoned branches automatically after a grace period.
  • Integrate with Jira via io.kestra.plugin.jira.issues.Create to notify branch owners directly if feature branches exceed 60 days of inactivity.
  • Export repository hygiene metrics to PostgreSQL or BigQuery for team velocity and engineering health reporting.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.