Shows what will change in your Fleet environment before you apply. Compares fleet-gitops YAML against the live Fleet API. Read-only (GET only).
Run in CI before fleetctl gitops --dry-run. fleet-plan shows what changes. fleetctl validates whether it's valid.
Maintained by the CampusTech IT & Infrastructure team.
| Feature | Description |
|---|---|
| Semantic diff | Compares YAML against live Fleet state per-field, not line-by-line |
| Team-scoped | Diff one team, multiple teams, or all teams at once |
| CI integration | --git auto-detects GitLab/GitHub, resolves changed files, posts MR/PR comment |
| Multi-env merge | --base + --env merges config overlays in-memory (no yq needed) |
| Script diffing | Line-count diffs for team scripts (+N/-N, ~N for single-line) |
| Label validation | Cross-references labels against Fleet, shows host counts |
| Multiple formats | Terminal (colored), JSON, Markdown |
| Read-only | GET requests only, never mutates Fleet |
Grab a binary from Releases.
# All teams fleet-plan # Single team fleet-plan --team Workstations # CI mode: auto-detect changed files, diff affected teams, post MR comment fleet-plan --git --base base.yml --env environments/prod.yml --format markdown
| Subcommand | Details | Example |
|---|---|---|
| (default) | Diff proposed YAML against live Fleet state | fleet-plan |
version |
Print version, build date, Go version, OS/arch | fleet-plan version |
| Flag | Details | Example |
|---|---|---|
--url |
Fleet server URL (or $FLEET_URL) |
--url https://fleet.example.com |
--token |
API token (or $FLEET_TOKEN) |
--token fleetctl-abc123 |
--repo |
Path to fleet-gitops repo (default: .) |
--repo /opt/fleet-gitops |
--team |
Diff only these teams (repeatable) | --team Workstations --team Servers |
-f, --format |
Output format: terminal, json, markdown |
-f markdown |
--no-color |
Disable color output | --no-color |
-v, --verbose |
Show full old/new values for modified fields | -v |
--heading |
Custom heading for markdown output | --heading "Staging diff" |
--detailed-exitcodes |
Exit 2 when changes detected (0=none, 1=error) | --detailed-exitcodes |
--git |
CI mode: auto-detect platform, resolve changed files, infer teams, post MR/PR comment (requires --format markdown) |
--git |
--base |
Path to base.yml for multi-env config merge (requires --env) |
--base base.yml |
--env |
Path to environment overlay YAML, merged with --base in-memory |
--env environments/prod.yml |
| Scope | Resources |
|---|---|
Team (teams/*.yml) |
Policies, queries, software, MDM profiles, scripts |
Global (default.yml) |
org_settings, agent_options, controls, global policies/queries, labels |
Use fleetctl gitops --dry-run for secret substitution, server-side validation, environment merging.
Set via flags, environment variables, or a config file. Config file search order (first found wins):
<repo>/.config/fleet-plan.json~/.config/fleet-plan.json
# Env vars (CI) export FLEET_URL=https://fleet.example.com export FLEET_TOKEN=your-token # Or flags fleet-plan --url https://fleet.example.com --token your-token
{
"contexts": {
"dev": {
"url": "https://dev.fleet.example.com",
"token": "..."
}
},
"default_context": "dev"
}Use --git to auto-detect the CI platform (GitHub Actions or GitLab CI), resolve changed files from the MR/PR, infer affected teams, and post a diff comment:
fleet-plan \ --git \ --base base.yml \ --env environments/prod.yml \ --format markdown \ --detailed-exitcodes
When --git is active, fleet-plan:
- Detects the CI platform from environment variables
- Fetches the list of changed files from the MR/PR API (falls back to
git diff) - Resolves which teams reference those files
- Diffs only the affected teams and global config
- Posts (or updates) a comment on the MR/PR with the diff
| Env var | Used for |
|---|---|
FLEET_URL / FLEET_TOKEN |
Fleet API auth |
FLEET_PLAN_INSECURE |
Set to 1 to allow plain HTTP connections (local dev only) |
FLEET_PLAN_BOT |
GitLab: token for posting MR comments |
GITHUB_TOKEN |
GitHub: token for posting PR comments |
CI_JOB_URL / GITHUB_SERVER_URL + GITHUB_REPOSITORY + GITHUB_RUN_ID |
Link back to the pipeline job in the comment |
PR_NUMBER / GITHUB_PR_NUMBER / GITHUB_EVENT_PATH |
PR number detection (fallback order: explicit env vars, then event payload JSON) |
- Architecture - data flow, packages, diff matching keys
- API Endpoints - every GET endpoint fleet-plan calls
-
GitOps API token has partial software and profile access. Verified against Fleet 4.90.1 with a
gitopsrole token:Endpoint Result /software/titles(list)200 — readable, so software is diffed /software/titles/{id}(detail)403 /software/fleet_maintained_apps200 /mdm/profiles403 Because the detail endpoint is refused, a Fleet-maintained app's categories cannot be read with a
gitopstoken.fleet-planreportsfleet-maintained app categories not diffed: API token lacks permission to read software title detailsrather than treating the unreadable value as empty, which would showcategories: [] → [X]for every app on every run. Install/uninstall scripts for those apps are likewise not compared. Use a token with broader read access if you need category and script diffs. Tracked upstream: fleetdm/fleet#38044.
See CONTRIBUTING.md. To report a security issue, see SECURITY.md.
git clone https://github.com/CampusTech/fleet-plan.git && cd fleet-plan go test -race ./...
fleet-plan was created by TsekNet, who wrote the original implementation and transferred the project to CampusTech. Thank you.