How to Build a Self-Hosted GitOps Workflow

Overview

GitOps is a deployment model where Git becomes the source of truth for desired system state. Instead of applying infrastructure or application changes directly to a cluster or server, your team updates declarative configuration in a repository. A controller running inside the target environment watches that repository, compares the desired state with the actual state, and reconciles differences.

In practice, a self-hosted GitOps workflow usually combines four layers:

• Git hosting for source code, manifests, and audit history
• CI to build artifacts, run tests, and publish immutable images or packages
• A GitOps controller to pull desired state from Git and apply it to the target environment
• Observability and policy controls to detect drift, failed syncs, and unsafe changes

The main benefit is not just automation. It is operational clarity. When deployment state lives in versioned files, teams can review it, roll it back, branch it, and discuss it like application code. That makes GitOps especially useful for Kubernetes, platform engineering, internal developer platforms, and any team that wants stronger release discipline without relying on ad hoc shell access.

A self-hosted approach is often a good fit when you need tighter control over security boundaries, network paths, data locality, or enterprise governance. It can also appeal to teams already investing in open source hosting, self hosted CI/CD, or internal developer infrastructure. If you are still comparing the surrounding ecosystem, the broader tool landscape is worth reviewing alongside this guide, including references such as Open Source DevOps Tools Stack: A Practical Reference by Category and Best Open Source Git Hosting Platforms Compared.

For this article, assume a common target pattern: a team runs one or more Kubernetes clusters, stores app and environment configuration in Git, uses CI to build container images, and wants a repeatable way to promote changes from development to production. The same principles can extend to non-Kubernetes systems, but Kubernetes remains the clearest reference model for a self-hosted GitOps workflow.

How to compare options

The market around GitOps changes regularly, but the comparison framework is stable. When evaluating open source GitOps tools or designing an argocd alternative path, compare options against your operating model rather than feature checklists alone.

1. Pull-based versus push-based deployment

The defining GitOps pattern is usually pull-based: the controller inside the cluster fetches desired state and applies it locally. This reduces the need to expose cluster credentials to external CI systems. A push-based system can still be automated and reproducible, but it behaves more like conventional CI/CD. If your goal is a durable self-hosted GitOps workflow, start with pull-based reconciliation unless you have a clear reason not to.

2. Repository structure and ownership model

Ask how your team wants to split ownership. Common choices include:

• Monorepo for app code and deployment config together
• Separate app and environment repos to isolate release management
• Platform repo plus service repos for larger organizations

This decision affects access controls, review paths, and blast radius. Small teams often move faster with fewer repositories. Larger teams usually benefit from clearer separation between application delivery and platform governance.

3. Manifest strategy

Your controller matters, but your manifest approach often matters more over time. Compare whether your team is comfortable with:

• Raw YAML for maximum transparency
• Kustomize-style overlays for environment differences
• Helm-style templating for reusable packaging
• Jsonnet, CUE, or similar tools for stronger abstraction

The most maintainable option is usually the least abstract one that still avoids duplication. Too little structure creates copy-paste drift. Too much abstraction turns deployment reviews into puzzle-solving.

4. Reconciliation and drift handling

A GitOps controller should do more than deploy. It should make drift visible and reconciliation predictable. Compare:

• How often sync runs
• Whether drift is auto-corrected or only reported
• How health checks and failed syncs are surfaced
• How rollbacks are handled when the desired state is invalid

Some teams prefer aggressive auto-sync in lower environments and more manual promotion in production. That split is common and sensible.

5. Secrets and sensitive configuration

One of the first practical hurdles in any GitOps deployment guide is secrets. Do not treat this as an add-on. Compare workflows based on how they handle encryption, secret injection, and rotation. A healthy baseline is:

• Keep plain secrets out of Git
• Store only encrypted values or references in version control
• Use cluster-local decryption or external secret operators where possible
• Separate secret ownership from application deployment ownership when needed

If your secret strategy feels awkward during the design phase, it will likely become fragile in production.

6. Multi-environment promotion

Deployment maturity often depends on promotion design. Compare whether your workflow promotes by:

• Merging changes across environment branches
• Updating image tags in environment folders
• Using pull requests to promote from dev to staging to production
• Releasing immutable bundles across environments

Whatever method you choose, the key is to make promotion explicit and reviewable. Hidden promotion logic inside CI jobs tends to age poorly.

7. Operational burden

Because this is self-hosted GitOps, you are also choosing what your team must maintain. Include these questions in your comparison:

• How hard is the controller to upgrade?
• Does it need its own database or external dependencies?
• Can teams self-serve, or does every change route through platform engineers?
• How easy is it to recover after a controller outage?

For many teams, the best open source GitOps tool is not the most feature-rich one. It is the one the team can operate confidently six months later.

Feature-by-feature breakdown

A durable GitOps workflow is less about product branding and more about how the moving parts fit together. The following reference architecture works well for many self-hosted environments.

Git hosting

You need a reliable Git server with branch protections, pull request review, and audit-friendly history. For some teams, a self-hosted Git service is enough. Others want a fuller developer hosting platform with integrated issues, runners, permissions, and package registries. If you are still deciding on that layer, compare options with Best Self-Hosted Developer Platforms for Internal Teams.

At minimum, create clear repository boundaries:

• Application repo: source code, tests, Dockerfile, and optionally deployment templates
• Environment repo: cluster-specific manifests, overlays, policies, and promotion history
• Platform repo: shared operators, ingress, observability, and cluster services

This separation makes it easier to assign ownership and avoid accidental production coupling.

CI pipeline

CI remains important in a GitOps workflow, but its job changes. CI should build, validate, sign, and publish artifacts; it should not be the final source of deployment truth. A practical CI pipeline usually does the following:

1. Run unit and integration tests
2. Build an immutable container image
3. Tag the image with a commit-derived identifier
4. Run security or policy checks appropriate to your environment
5. Update the deployment repository with the new image reference through a pull request or automated commit

That last step is the handoff from CI to GitOps. Rather than pushing directly to the cluster, CI updates Git. The controller sees Git change and performs reconciliation. If you are selecting the surrounding CI system, these comparisons may help: Jenkins Alternatives: Open Source CI Servers Worth Evaluating and Self-Hosted CI/CD Tools Comparison for Small Teams and Enterprises.

GitOps controller

Your controller is the heart of the system. Whether you choose a popular controller, a lighter alternative, or a more tightly scoped reconciliation model, the core responsibilities are similar:

• Watch repositories or registry-backed config sources
• Compare desired and live state
• Apply changes safely
• Report health and sync status
• Support rollbacks through Git history

When comparing an established option against an argocd alternative, focus on these practical questions:

• Can it model your repository layout cleanly?
• Does it support your preferred manifest style?
• Will it scale to your number of clusters and applications?
• Does it expose enough visibility for on-call work?
• Can teams understand it without vendor-specific training?

The right answer varies. Platform teams often prefer richer application modeling and visibility. Smaller teams may prefer fewer moving parts and simpler reconciliation semantics.

Configuration management

Most GitOps implementations become hard to maintain when environment differences grow. To avoid that, pick one primary configuration strategy and document it early.

A balanced approach often looks like this:

• Use a shared base for common resources
• Use overlays or values files for environment-specific differences
• Keep per-environment changes small and reviewable
• Avoid generating large opaque outputs that reviewers cannot reason about

If you need highly reusable application packaging across many services, Helm-style packaging may fit. If you prioritize direct readability and patch-based customization, Kustomize-style overlays may age better. What matters most is consistency.

Secrets and policy

Every self-hosted GitOps workflow needs explicit rules for secrets, identity, and policy. A practical baseline includes:

• Use external secret backends or encrypted secret manifests
• Restrict controller permissions to the namespaces and resources it actually manages
• Use admission or policy controls for high-risk resources
• Require pull request review for production changes
• Log reconciliation failures and policy denials centrally

This is where many teams discover that GitOps is not just a deployment tool. It is a governance pattern. The audit trail is only useful if access and review controls are equally well designed.

Observability and failure handling

A mature workflow treats failed reconciliation as a first-class operational event. Add visibility for:

• Sync status by application and cluster
• Drift detection and auto-remediation outcomes
• Controller health and queue backlogs
• Deployment frequency and rollback events
• Manifest validation and policy failures

Without this layer, GitOps can feel invisible until it breaks. With it, teams can reason about delivery as a normal part of operations.

A simple end-to-end flow

Here is a practical, low-friction GitOps workflow many teams can adopt:

1. A developer merges code into the main branch of an application repo.
2. CI runs tests and builds a new container image.
3. CI publishes the image to a registry with an immutable tag.
4. CI opens a pull request against the environment repo to update the image reference for development.
5. After review or policy checks, that pull request merges.
6. The GitOps controller detects the change and deploys it to the development cluster.
7. Promotion to staging and production happens through separate pull requests, not hidden pipeline steps.

This model is easy to audit, easy to roll back, and easier for new team members to understand than a deeply scripted CI pipeline.

For adjacent deployment patterns, see Open Source Deployment Tools for Docker and Kubernetes and How to Deploy from Git: Open Source Platforms and Workflows Explained.

Best fit by scenario

Different teams need different GitOps shapes. These scenarios can help narrow the right design.

Small team, one cluster, limited platform staff

Choose the simplest path that preserves reviewability. Use:

• One Git host
• One CI system
• One GitOps controller
• A small number of repositories
• Minimal abstraction in manifests

Favor straightforward overlays, explicit promotions, and a short runbook. Avoid premature multi-cluster complexity.

Growing SaaS team with separate environments

Split application and environment concerns. Use CI to publish immutable artifacts and update environment repos through pull requests. Add policy checks before production merges. This gives product teams autonomy while preserving an audit trail.

Platform engineering team supporting many services

Create a platform repo for shared services and cluster add-ons, and separate service repos for application ownership. Standardize templates and policy controls, but avoid forcing every service into a complex framework on day one. Internal documentation matters as much as tooling here.

Regulated or security-sensitive environment

Prefer pull-based reconciliation, narrowly scoped permissions, strong review controls, and a documented secret management model. Keep direct cluster access rare and exceptional. Git history should explain not only what changed, but who approved it and why.

Hybrid estate with Kubernetes plus non-Kubernetes systems

Use GitOps where declarative state is strongest, and do not force it everywhere. It is fine to keep some conventional automation for legacy systems while standardizing review, versioning, and promotion patterns across both models.

When to revisit

A GitOps workflow should be stable, but not frozen. Revisit your design when the underlying constraints change. This topic is especially worth returning to when pricing, features, or policies change in the tools around your stack, or when new options appear that reduce operational burden.

More specifically, review your workflow when:

• You add clusters, regions, or business-critical environments
• Your repository structure starts causing ownership confusion
• Promotion between environments becomes slow or error-prone
• Secrets handling feels bolted on rather than designed in
• The controller becomes a single point of confusion for on-call engineers
• Developers cannot tell whether deployment failures are caused by CI, Git state, or cluster state
• You need stronger policy, tenancy, or compliance controls

Use the following maintenance checklist every quarter or after a major platform change:

1. Audit repository boundaries. Confirm that ownership and permissions still match how teams actually work.
2. Review promotion flow. Make sure releases are still explicit, visible, and easy to rollback.
3. Test controller recovery. Verify how reconciliation resumes after failures or upgrades.
4. Inspect secrets handling. Remove any workflow that still depends on plain secrets in Git or uncontrolled manual steps.
5. Trim abstraction. If deployment config has become too clever to review, simplify it.
6. Update runbooks. New engineers should be able to follow the delivery path without tribal knowledge.
7. Re-compare tools. Periodically reassess whether your current controller, CI, or Git hosting still fits better than available alternatives.

If your team is building a broader internal stack around this workflow, keep related references close at hand, including Open Source Platform as a Service Options for Web Apps and CI/CD best practices for open source projects and external contributors.

The practical next step is simple: map your current deployment path on one page. Identify where state lives, who approves changes, how artifacts are published, where secrets come from, and how production promotion happens. If any of those answers live outside Git, outside review, or only in someone’s memory, that is the area to fix first. A good self-hosted GitOps workflow is not the one with the most components. It is the one that makes change understandable, reversible, and routine.