The simplest way to make Gitea HAProxy work like it should

Your developers just want to push code, run reviews, and forget about reverse proxy drama. Instead, they’re stuck diagnosing why Gitea refuses to behave behind HAProxy. One bad header or missing proxy setting, and suddenly webhooks fail or SSH access mysteriously times out. It’s a classic DevOps headache.

Gitea, the lightweight Git service, loves simplicity. HAProxy, the battle-tested load balancer, thrives on precision. Used together, they deliver private Git hosting that actually scales, with proper TLS, sticky sessions, and access control that won’t crumble under load. The trick is wiring them together in a way that keeps both fast and sane.

At its core, Gitea HAProxy integration does one thing: separates responsibility. Gitea focuses on repositories, webhooks, and identity. HAProxy takes care of routing, SSL termination, health checks, and traffic shaping. When you connect the two correctly, you get predictable URLs, reliable redirects, and a perimeter that makes compliance teams smile.

How it works
HAProxy listens publicly, handling HTTPS requests and forwarding them to one or more internal Gitea instances. It adds headers like X-Forwarded-Proto to preserve original connection context and can enforce strong client SSL policies or IP allowlists. Gitea, configured to trust the proxy, rebuilds the correct URLs for users and API responses. That clean separation improves security posture and simplifies scaling: new nodes register behind HAProxy with zero client disruption.

Best practices
Use sticky sessions only when you rely on in-memory session state. Prefer stateless authentication tokens via OIDC or OAuth2 for distributed teams. Keep HAProxy health checks lightweight and frequent to catch dead backends early. Most importantly, enable TLS 1.3 and restrict ciphers to modern suites, especially if you integrate with identity providers like Okta or Keycloak.

Gitea HAProxy troubleshooting tip
If users see mixed HTTP/HTTPS assets or fail to authenticate via your IdP, check reverse proxy headers. Ninety percent of misbehavior comes from missing or duplicated headers, not the app itself.

Key benefits

• Single point for TLS and rate limiting across all repos
• Easier audit logging for SOC 2 or ISO 27001 reviews
• Smooth horizontal scaling of Gitea application servers
• Reliable SSH and HTTP routes even during node restarts
• Reduced operational noise when onboarding new repos

For developers, this setup means fewer broken webhooks and faster merges. HAProxy keeps Gitea snappy by distributing load intelligently and rewriting only what’s necessary. Your CI pipelines feel faster, not because of magic, but because latency and retries drop to near zero.

Platforms like hoop.dev turn those access rules into guardrails that enforce policy automatically. Instead of maintaining proxy ACLs by hand, you define intent once, and it keeps every endpoint behind an identity-aware boundary. It’s the kind of automation that feels invisible until you realize you haven’t fought a proxy issue in weeks.

How do I connect Gitea and HAProxy?
Point HAProxy’s backend to your internal Gitea instance, enable X-Forwarded-* headers, and configure Gitea to trust the proxy by setting its ROOT_URL accordingly. That’s it. No plugin, no custom code, just proper proxy hygiene.

AI agents and copilots thrive on reliable APIs. With Gitea behind HAProxy, you can expose secure endpoints for automated code review or dependency triage without worrying that an internal token leaks through misconfigured routing. Clean boundaries make safe automation possible.

When Gitea and HAProxy work together, version control becomes reliable infrastructure, not fragile plumbing.

See an Environment Agnostic Identity-Aware Proxy in action with hoop.dev. Deploy it, connect your identity provider, and watch it protect your endpoints everywhere—live in minutes.