Fleet GitOps

Important

This repository is deprecated and will be archived. The recommended way to start a Fleet GitOps repository is now the fleetctl new command, which generates an up-to-date starter directory with CI/CD workflows for GitHub Actions and GitLab.

Repositories already cloned from here keep working, and this repo stays available for reference, but it no longer receives updates. New repositories should use fleetctl new (see Getting started below).

This was the starter repository for using Fleet with a GitOps workflow.

Why use GitOps?

Getting started

To start a new Fleet GitOps repository, install fleetctl and run fleetctl new. The manage devices as code reference in the Fleet docs walks through the full setup and every configuration option.

GitOps mode

Once you're set up with GitOps in Fleet, you can optionally put the UI in GitOps mode. This prevents you from making changes in the UI that would be overridden by GitOps workflows.

An admin can enable GitOps mode in Settings > Integrations > Change management.

Note that this is a UI-only setting. API permissions are restricted based on user role.

Legacy setup

The steps below apply to repositories that were already cloned from this starter. New repositories should use fleetctl new instead.

GitHub setup

1. Clone the GitHub repository, create your own GitHub repository, and push your clone to your new repo. Note that a workflow will run once and fail because the required variables haven't been added (step 2).

2. Add FLEET_URL and FLEET_API_TOKEN secrets to your new repository's secrets. Learn how here. Set FLEET_URL to your Fleet instance's URL (ex. https://organization.fleet.com). Create an API-only user with the "GitOps" role and set FLEET_API_TOKEN to your user's API token. If you're using Fleet Free, set the API-only user's role to global admin.

3. In GitHub, enable the Apply latest configuration to Fleet GitHub Actions workflow, and run workflow manually. Now, when anyone pushes a new commit to the default branch, the action will run and update Fleet. For pull requests, the workflow will do a dry run only.

GitLab setup

1. Clone the GitLab repository, create your own GitLab repository, and push your clone to your new repo. Note that a pipeline will run once and fail because the required variables haven't been added (step 2).

2. Add FLEET_URL and FLEET_API_TOKEN as masked CI/CD variables. Learn how here. Set FLEET_URL to your Fleet instance's URL (ex. https://organization.fleet.com). Set FLEET_API_TOKEN to an API token for an API-only user in Fleet. Learn how here, then, grant it the GitOps role via the Settings > Users page so it can make changes.

3. Now, when anyone pushes a new commit to the default branch, the pipeline will run and update Fleet. For merge requests, the pipeline will do a dry run only.

4. To ensure your Fleet configuration stays up to date even when there are no new commits, set up a scheduled pipeline:

   • In your GitLab project, go to the left sidebar and navigate to Build > Pipeline schedules. (In some GitLab versions, this may appear as CI/CD > Schedules.)
   • Click Create a new pipeline schedule (or Schedule a new pipeline).
   • Fill in the form:
     • Description: e.g., Daily GitOps sync
     • Cron timezone: e.g., [UTC 0] UTC
     • Interval pattern: e.g., Custom: 0 6 * * * (runs nightly at 6AM UTC)
     • Target branch or tag: your default branch (e.g., main)
   • Click Create pipeline schedule.