What is a GitRepository source in FluxCD and how does it connect a Git repo to the cluster?

Think of a GitRepository resource as a subscription to a newspaper. You tell the newspaper company (source-controller) which paper you want (repository URL), which edition (branch or tag), how often to check for new issues (interval), and your delivery credentials (SSH key or token). The source-controller then delivers the latest content to your doorstep (makes it available as an artifact) for other Flux controllers to read.

A GitRepository is one of several source types in FluxCD, alongside HelmRepository, OCIRepository, and Bucket. It is a Kubernetes custom resource defined in the source.toolkit.fluxcd.io API group. When you create a GitRepository resource, the source-controller begins monitoring the specified Git repository at the configured interval. On each poll, it checks whether the commit SHA at the tip of the specified branch (or tag) has changed. If it detects a new commit, it performs a shallow clone of the repository, packages the contents of the specified path into a tarball artifact, and stores it internally. This artifact is then available for consumption by Kustomization or HelmRelease resources that reference this GitRepository as their source.

Authentication for private repositories is handled through Kubernetes secrets. For SSH-based access, you create a secret containing an SSH private key and optionally known_hosts data. For HTTPS-based access, the secret contains a username and password or personal access token. The Flux bootstrap process automatically creates a deploy key and the corresponding secret for the fleet repository, but additional GitRepository sources for application repositories require manual secret creation. Flux also supports GPG signature verification, allowing you to ensure that only signed commits are applied to the cluster.

The GitRepository resource provides several important configuration options. The interval field determines how frequently the source-controller polls for changes, with typical values ranging from one minute for active development to ten minutes for stable infrastructure. The ref field specifies which Git reference to track: a branch, a tag, a semver range, or a specific commit SHA. Semver ranges are particularly useful for tracking the latest patch version of a release (e.g., >=1.0.0 <2.0.0). The ignore field lets you exclude files from the artifact using .gitignore-style patterns, which is useful for excluding documentation or test files that should not trigger reconciliation.

In production, teams typically create multiple GitRepository sources: one for the fleet infrastructure repository managed by the platform team, and additional ones for application repositories managed by development teams. The source-controller adds status conditions to each GitRepository resource, including the last fetched revision, the artifact URL, and any errors encountered during the fetch. Monitoring these status conditions is essential for detecting repository connectivity issues, expired credentials, or branch deletion. Teams should set up Flux alerts to notify them when a GitRepository enters a failed state, as this silently stops all deployments that depend on that source.