GitOps Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- articles/the-gitops-idea.md
- articles/managing-linux-desktops-with-gitops.md
- articles/preventing-mistakes-with-gitops.md
- articles/gitops-mode-software.md
- articles/the-cost-of-code-as-config.md
- articles/sysadmin-diaries-gitops-a-strategic-advantage.md
- articles/what-i-have-learned-from-managing-devices-with-gitops.md
- articles/migrating-to-gitops-using-fleetctl.md
- tools/fleet-slackbot/system-prompt.js
GitOps Configuration in Fleet is an operational framework that treats infrastructure and device management as code. By leveraging version control (Git), declarative YAML files, and CI/CD pipelines, Fleet allows organizations to maintain a single source of truth for their device states, including policies, labels, software, and OS updates. This approach replaces traditional manual "ClickOps" workflows with auditable, repeatable, and automated processes.
Sources: articles/preventing-mistakes-with-gitops.md, articles/managing-linux-desktops-with-gitops.md
Core Architecture and Logic
The GitOps system in Fleet relies on a reconciliation loop. A desired state is defined in YAML files within a Git repository. A CI/CD runner (such as GitHub Actions or GitLab CI) executes the fleetctl gitops command, which compares the defined state in the repository against the live state of the Fleet instance. Fleet then reconciles its internal configuration to match the code, creating new resources and removing or resetting undefined ones.
Sources: articles/managing-linux-desktops-with-gitops.md, articles/the-gitops-idea.md
Data Flow Overview
The following diagram illustrates the standard GitOps workflow from code change to device enforcement:
The workflow ensures that human operators are removed from direct production access, using automation runners as the primary interface for change.
Sources: articles/managing-linux-desktops-with-gitops.md, articles/preventing-mistakes-with-gitops.md
Key Components
| Component | Description |
|---|---|
| Declarative YAML | Files describing the desired state of fleets, policies, and controls. |
| fleetctl gitops | The CLI command responsible for deploying configuration and performing dry runs. |
| GitOps Mode | A read-only UI setting that prevents manual changes that would be overridden by code. |
| GitOps Role | A specific API-only user role for automation runners, ensuring separation of concerns. |
| GitOps Exceptions | A feature allowing specific resources (software, labels, etc.) to be managed via UI while others stay in Git. |
Sources: articles/managing-linux-desktops-with-gitops.md, articles/the-cost-of-code-as-config.md
Configuration Structure
Fleet GitOps configurations are typically organized into a directory structure that promotes modularity and reusability.
Repository Layout
A standard repository (often based on the Fleet starter template) includes:
default.yml: Global organization settings and shared labels.fleets/: YAML files for specific groups (e.g.,workstations.yml,servers.yml).lib/: A library of reusable configurations (policies, scripts, and software definitions) referenced by fleet files.
Sources: tools/fleet-slackbot/system-prompt.js, articles/managing-linux-desktops-with-gitops.md
YAML Schema Examples
Fleet Configuration File
Fleet files reference library items by relative paths.
name: "Workstations"
policies:
- path: ../lib/linux/policies/internal-certificate.yml
controls:
scripts:
- path: ../lib/linux/scripts/install-internal-ca.sh
Sources: articles/managing-linux-desktops-with-gitops.md, tools/fleet-slackbot/system-prompt.js
Policy Definition
Policies define SQL queries to check for compliance and optional remediation scripts.
- name: "Internal CA Certificate"
query: SELECT 1 FROM certificates WHERE sha1 = '28752f8e3f499d852dc5d86f1caca0d8'
platform: linux
run_script:
path: ../scripts/install-internal-ca.sh
Sources: articles/managing-linux-desktops-with-gitops.md, tools/fleet-slackbot/system-prompt.js
Migration and Tooling
Fleet provides utilities to transition existing "ClickOps" environments into GitOps.
fleetctl generate-gitops
This command exports the current Fleet configuration into GitOps-ready YAML files. It organizes them according to best practices and identifies sensitive information (like enrollment secrets) that should be moved to environment variables.
Sources: articles/migrating-to-gitops-using-fleetctl.md, articles/managing-linux-desktops-with-gitops.md
Sensitive Information Handling
To avoid security risks, GitOps configuration supports environment variable interpolation.
org_settings:
server_settings:
server_url: $FLEET_URL
Sources: articles/managing-linux-desktops-with-gitops.md, articles/migrating-to-gitops-using-fleetctl.md
GitOps Mode and Governance
"GitOps Mode" is a strategic feature used to prevent configuration drift. When enabled, the Fleet UI becomes read-only for settings managed by Git. This forces all changes through the Git workflow (pull requests, code reviews, and automated tests).
Software Management via GitOps
Software management in GitOps covers three types of applications:
- Custom Packages: Managed via the
packageskey. For script-based packages, the file content itself becomes the install script. - App Store Apps: Managed via VPP (Apple) or Google Play (Android).
- Fleet-maintained Apps: Common applications maintained by Fleet, referenced by slugs (e.g.,
google-chrome/macos).
Sources: articles/gitops-mode-software.md, tools/fleet-slackbot/system-prompt.js
Conclusion
GitOps Configuration in Fleet provides a robust, auditable, and scalable method for managing device fleets. By codifying configuration and automating its application, IT teams reduce the risk of human error, eliminate configuration drift, and ensure that the state of all devices matches the documented "source of truth" in Git.
Sources: articles/the-gitops-idea.md, articles/preventing-mistakes-with-gitops.md