Configuration baselines
simply gitlab config apply
Section titled “simply gitlab config apply”Bring projects onto a baseline config.
Flags
-c, --config <value>— Path to the baseline configuration file. (required)--target <value>— Limit the run to this project path. Repeatable.--concurrency <value>— How many targets to work on at once. (default:4)--fail-fast— Stop at the first target that fails instead of continuing.--dry-run— Print the request that would be sent and exit without sending it.
Connection
-e, --env-file <value>— Path to a .env file holding connection settings.--gitlab-url <value>— Base URL of the GitLab instance. Defaults to https://gitlab.com. (env:GITLAB_URL)--gitlab-token <value>— Personal, project, or group access token. (env:GITLAB_TOKEN)
Global
--json— the raw API payload, for scripts and agents.
Computes the same plan as config plan, then executes it. Only what the plan showed is sent, so a preview is a guarantee rather than an approximation, and a second run against a converged project sends no requests at all.
Sections are applied in a fixed order — settings, protected branches, protected tags, approval settings, approval rules, push rules — because an approval rule scoped to a branch needs that branch protected before it can reference it.
By default the config only adds and corrects what it declares. A section that sets “prune”: true also deletes entries the config does not mention.
One target failing does not abandon the rest; the summary says which ones failed and where they stopped. There is no transaction across GitLab endpoints, so a target that failed part-way keeps the sections already applied — run config plan afterwards to see what is left.
Examples
simply gitlab config apply --config ./baseline.json --dry-runsimply gitlab config apply --config ./baseline.jsonsimply gitlab config apply --config ./baseline.json --target group/projectsimply gitlab config export
Section titled “simply gitlab config export”Write a baseline config describing an existing project.
Flags
-p, --project <value>— Project id, or its full path such as group/subgroup/project. (required; env:GITLAB_PROJECT)--section <value>— Comma-separated sections to export. Defaults to all of them. (one of:settings,protectedBranches,protectedTags,approvals,approvalRules,pushRules,variables; repeatable)
Connection
-e, --env-file <value>— Path to a .env file holding connection settings.--gitlab-url <value>— Base URL of the GitLab instance. Defaults to https://gitlab.com. (env:GITLAB_URL)--gitlab-token <value>— Personal, project, or group access token. (env:GITLAB_TOKEN)
Global
--json— the raw API payload, for scripts and agents.
Reads one project and prints a configuration file that describes it, ready to be edited and pointed at the rest of your projects. Writing a baseline by hand against forty attributes is miserable and the first draft is wrong; exporting the project that already looks right and deleting what you do not care about is the way to start.
The output is deliberately verbose — every supported key, not a curated subset — because deleting a line is easier than discovering that a key exists. Variables are exported as metadata only: keys, scopes, and flags, never values.
The exported targets name only the project it came from. Widen that on purpose rather than inheriting a blast radius from an export.
Examples
simply gitlab config export --project group/project > baseline.jsonsimply gitlab config export --project group/project --section settings,protectedBranchessimply gitlab config plan
Section titled “simply gitlab config plan”Report how projects differ from a baseline config.
Flags
-c, --config <value>— Path to the baseline configuration file. (required)--target <value>— Limit the run to this project path. Repeatable.--concurrency <value>— How many targets to work on at once. (default:4)--fail-fast— Stop at the first target that fails instead of continuing.--fail-on-drift— Exit 1 when any target differs from the baseline.
Connection
-e, --env-file <value>— Path to a .env file holding connection settings.--gitlab-url <value>— Base URL of the GitLab instance. Defaults to https://gitlab.com. (env:GITLAB_URL)--gitlab-token <value>— Personal, project, or group access token. (env:GITLAB_TOKEN)
Global
--json— the raw API payload, for scripts and agents.
Reads the baseline, expands its targets, and prints what differs on each one. Nothing is sent that changes anything, so this is safe to run against every project you have.
Only the attributes the config declares are compared. A project with forty settings the config never mentions shows nothing for them — that is what makes a baseline safe to point at projects that already exist.
Entries that exist on the instance but are not in the config are shown as removals, marked as not pruned unless that section opts into pruning. Seeing what you are choosing not to fix is most of the value of running this across fifty projects.
Use —fail-on-drift in a scheduled job: it exits 1 when anything differs, so CI can tell you that something drifted without anyone having to read the output.
Examples
simply gitlab config plan --config ./baseline.jsonsimply gitlab config plan --config ./baseline.json --target group/projectsimply gitlab config plan --config ./baseline.json --fail-on-driftsimply gitlab config plan --config ./baseline.json --json | jq .summary