fleet-plan

README

fleet-plan

terraform plan, but for Fleet.

---

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.

Features

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

Install

Grab a binary from Releases.

Quick start

# 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

Usage

Subcommands

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

Flags

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

What it diffs

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.

Configuration

Auth

Set via flags, environment variables, or a config file. Config file search order (first found wins):

1. <repo>/.config/fleet-plan.json
2. ~/.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"
}

CI integration

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:

1. Detects the CI platform from environment variables
2. Fetches the list of changed files from the MR/PR API (falls back to git diff)
3. Resolves which teams reference those files
4. Diffs only the affected teams and global config
5. 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)

Documentation

• Architecture - data flow, packages, diff matching keys
• API Endpoints - every GET endpoint fleet-plan calls

Known Limitations

• GitOps API token has partial software and profile access. Verified against Fleet 4.90.1 with a gitops role token:

  Endpoint	Result
  /software/titles (list)	200 — readable, so software is diffed
  /software/titles/{id} (detail)	403
  /software/fleet_maintained_apps	200
  /mdm/profiles	403

  Because the detail endpoint is refused, a Fleet-maintained app's categories cannot be read with a gitops token. fleet-plan reports fleet-maintained app categories not diffed: API token lacks permission to read software title details rather than treating the unreadable value as empty, which would show categories: [] → [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.

Contributing

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 ./...

Acknowledgements

fleet-plan was created by TsekNet, who wrote the original implementation and transferred the project to CampusTech. Thank you.

License

MIT