EnvSync

Environment orchestration through GitLab comments

Comment

Inspiration

Every team managing multiple environments (dev, staging, preprod, production) hits the same pain: cherry-picks get lost between branches, configs silently drift, and when a pipeline breaks on staging, someone has to manually SSH around to figure out if it's the code or the environment. We wanted to solve this entirely within GitLab — no external tools, no scripts, no dashboards to check. Just @mention a flow in any issue or MR and let it handle the rest.

What it does

EnvSync provides a suite of GitLab Duo Flows and an Agent that orchestrate code across environment branches:

  • EnvSync Core — @envsync status shows pipeline health across all environments. drift-check compares branches for unexpected differences (also runs on schedule via CI). cherry-pick moves specific commits between branches with three-tier intelligent conflict resolution. promote creates merge requests along the promotion chain. rollback reverts to a last known-good deployment with safety gates.
  • Pipeline Doctor — Automatically triggers on pipeline failure (via CI on_failure job), performs cross-environment triage by comparing logs and configs across branches, and posts a root cause diagnosis with confidence scores — all without anyone typing a command.
  • Rollback Guardian — Pre-rollback safety validator that checks deployment history, scans for irreversible database migrations, and produces a risk assessment before any rollback proceeds.
  • Conflict Resolver — Dedicated conflict analysis flow with three tiers: auto-resolve safe files (lockfiles, generated code), AI-proposed merges with confidence scores for human approval, and manual flagging with context for complex conflicts.
  • EnvSync Assistant — Read-only Duo Chat agent for querying environment topology, pipeline status, and drift without triggering any actions.

Everything is configured through a single envsync.yaml file that defines your environment topology, promotion chain, expected differences, conflict resolution rules, and rollback policies. Multi-project support lets you orchestrate across multiple repos with --all-projects flags.

How we built it

We built it entirely on the GitLab Duo Agent Platform (Flow track). Each flow is a YAML configuration with inline system prompts that guide Claude to use GitLab's built-in tools — get_repository_file, gitlab_api_get, create_commit, create_merge_request, create_issue_note, etc. No external APIs, no custom scripts.

The key architectural decisions:

  • Runtime config discovery — flows read envsync.yaml via get_repository_file, making the same flow work for any project
  • Dynamic project context — get_project discovers project ID at runtime, eliminating hardcoded values and enabling forks
  • CI integration — Pipeline failure auto-triage and scheduled drift checks use GitLab CI jobs as reliable trigger mechanisms
  • Component separation — Specialized flows for conflict resolution and rollback safety, each with prompts optimized for their specific task

Prompt engineering was critical: XML-tagged context injection for environment topology, structured chain-of-thought for log analysis, and explicit tool-use patterns that force the LLM to take action rather than just generate text.

Challenges we ran into

  • Flow scoping — We initially built a separate demo project (Verifai) but discovered flows are scoped to the group where they're published. We had to restructure everything into the hackathon sandbox.
  • Context discovery — The flow didn't know which project it was running in, causing it to ask users for project IDs. We iterated through several versions before landing on get_project with no arguments + dynamic ID resolution.
  • Invalid inputs — Using context:project_url and context:issue_url caused silent failures. The fix was using only context:goal and embedding project context in the system prompt.
  • Trigger engineering — GitLab Duo Flow event triggers are still evolving. We solved auto-triggering through CI when: on_failure jobs that post structured comments, bridging the gap between CI events and flow activation.
  • Conflict resolution confidence — Calibrating the confidence threshold for Tier 2 vs Tier 3 conflict resolution required testing across diverse conflict types. We settled on 0.8 as the default with per-project configuration.
  • Runner queue times — Shared runners during the hackathon meant 5–10 minute waits, making rapid iteration challenging.

Accomplishments we're proud of

  • It actually works. Eight real commands across four flows that take real action — not a chatbot, but an orchestration engine. (Here's a working example on our project)[https://gitlab.com/gitlab-ai-hackathon/participants/35525051/-/work_items/3].
  • Auto-triage pipeline failures — Pipeline Doctor fires automatically when any pipeline fails, performs cross-environment comparison, and posts a diagnosis before anyone even notices the failure.
  • Three-tier conflict resolution — Cherry-picks don't just fail on conflicts anymore. Safe files auto-resolve, the AI proposes merges for medium-complexity conflicts, and complex ones get flagged with full context for human review.
  • Rollback with safety gates — Rollback Guardian scans for irreversible migrations and blocks dangerous rollbacks. Protected environments require explicit confirmation.
  • Multi-project orchestration — One command to check pipeline status, drift, or cherry-pick across your entire microservice fleet.
  • Zero external dependencies — Everything runs on GitLab's built-in tools. Drop envsync.yaml in any project and you're done.

What we learned

  • GitLab Duo Flows are powerful but require careful prompt engineering — the LLM needs explicit project context and strong instructions to use tools instead of just generating text responses.
  • Specialized flows beat monolithic ones — separating conflict resolution and rollback safety into dedicated components with focused prompts produced far better results than cramming everything into one flow.
  • The ambient environment type is perfect for background automation triggered by comments.
  • CI jobs as trigger bridges (when: on_failure, $CI_PIPELINE_SOURCE == "schedule") fill the gap where platform-native event triggers aren't yet available.
  • Iterating on flow YAMLs through tag → pipeline → test cycles taught us to keep flows simple (single component beats multi-component chains for reliability).

What's next for EnvSync

  • Auto-rollback on critical failure — When Pipeline Doctor detects a critical regression with high confidence, optionally trigger an automatic rollback (with auto_rollback_on_failure: true)
  • Conflict resolution learning — Track which AI-proposed resolutions get accepted vs rejected to improve confidence calibration over time
  • Environment health dashboard — A persistent tracking issue that auto-updates with environment health metrics on every scheduled check
  • Branch protection automation — Automatically adjust branch protection rules based on environment risk levels
  • GitLab native event triggers — Migrate from CI job bridges to platform-native triggers: when GitLab Duo Flows support them natively

Built With

  • gitlab
Share this project:

Updates