GitLab's project API accepts either a numeric ID or a URL-encoded full path in
its {id} path parameter. The declared full path is percent-encoded as one
path segment.
The setting objects below are organizational sections. Their scalar
properties are flattened into one PUT /projects/:id request, so declare each
property in only one section. The fields below describe the scalar properties
accepted by GitLab's project-edit endpoint; the section placement is the
recommended grouping used throughout these examples.
|
path string Required
Full path of the project, including its group hierarchy.
|
Example:
gitlab_settings_projects:
- path: platform/engineering/service
...
|
|
project object
Visibility, description, and general project attributes. Scalar keys flatten into the project update.
Properties of project
name string
Display name of the project.
path string
URL path of the project. The entry's top-level path remains the lookup identity for the current run.
description string
Description shown on the project's overview page.
visibility string
Can be one of: private, internal, public.
avatar string (binary file)
Avatar image uploaded for the project.
emails_enabled boolean
Enable project email notifications.
show_default_award_emojis boolean
Show GitLab's default award emojis.
warn_about_potentially_unwanted_characters boolean
Warn users about potentially unwanted Unicode characters.
request_access_enabled boolean
Allow users to request membership in the project.
|
Example:
gitlab_settings_projects:
- path: platform/service
project:
visibility: private
...
|
|
features object
Project feature access levels. Scalar keys flatten into the project update.
Properties of features
Access-level properties can be disabled, private, or enabled.
issues_enabled boolean
Enable the issue tracker using the legacy boolean control.
merge_requests_enabled boolean
Enable merge requests using the legacy boolean control.
wiki_enabled boolean
Enable the project wiki using the legacy boolean control.
jobs_enabled boolean
Enable CI/CD jobs using the legacy boolean control.
snippets_enabled boolean
Enable project snippets using the legacy boolean control.
issues_access_level string
Issue tracker access level.
merge_requests_access_level string
Merge-request access level.
snippets_access_level string
Project-snippet access level.
wiki_access_level string
Project-wiki access level.
releases_access_level string
Release access level.
builds_access_level string
CI/CD build access level.
analytics_access_level string
Analytics access level.
environments_access_level string
Environment access level.
feature_flags_access_level string
Feature-flag access level.
infrastructure_access_level string
Infrastructure access level.
monitor_access_level string
Monitoring access level.
model_experiments_access_level string
Model experiment access level.
model_registry_access_level string
Model registry access level.
requirements_access_level string
Requirements feature access level.
pages_access_level string
GitLab Pages access. Unlike the other access-level properties, this also accepts public. Other Pages controls use the dedicated projects[].pages surface in Integrations and Services.
duo_remote_flows_enabled boolean
Enable GitLab Duo remote flows.
duo_sast_fp_detection_enabled boolean
Enable GitLab Duo SAST false-positive detection.
duo_secret_detection_fp_enabled boolean
Enable GitLab Duo Secret Detection false-positive detection.
duo_dependency_bump_breaking_changes_enabled boolean
Enable Agentic Breaking Change Resolution for dependency updates.
duo_sast_vr_workflow_enabled boolean
Enable the GitLab Duo SAST vulnerability-resolution workflow.
|
Example:
gitlab_settings_projects:
- path: platform/service
features:
issues_access_level: enabled
...
|
|
merge_requests object
Merge methods and merge-request policy. Scalar keys flatten into the project update.
Properties of merge_requests
merge_method string
Can be one of: ff, rebase_merge, merge.
squash_option string
Squash behavior. Can be one of: never, always, default_on, default_off.
remove_source_branch_after_merge boolean
Select source-branch removal by default after merge.
resolve_outdated_diff_discussions boolean
Automatically resolve diff discussions whose lines change in a later push.
only_allow_merge_if_pipeline_succeeds boolean
Require a successful pipeline before merging.
allow_merge_on_skipped_pipeline boolean
Treat a skipped pipeline as satisfying the successful-pipeline requirement.
only_allow_merge_if_all_discussions_are_resolved boolean
Require every discussion to be resolved before merging.
only_allow_merge_if_all_status_checks_passed boolean
Require every external status check to pass before merging.
printing_merge_request_link_enabled boolean
Show a merge-request create/view link after a Git push.
show_diff_preview_in_email boolean
Include code-diff previews in merge-request notification emails.
suggestion_commit_message string
Commit message used when applying merge-request suggestions.
merge_commit_template string
Template used to create merge commit messages.
squash_commit_template string
Template used to create squash commit messages.
issue_branch_template string
Template used to name branches created from issues.
issues_template string
Default GitLab Flavored Markdown description for new issues.
merge_requests_template string
Default GitLab Flavored Markdown description for new merge requests.
autoclose_referenced_issues boolean
Close referenced issues automatically when changes reach the default branch.
mr_default_title_template string
Template used for default merge-request titles.
merge_request_title_regex string
Regular expression that merge-request titles must match.
merge_request_title_regex_description string
User-facing explanation of the merge-request title rule.
approvals_before_merge integer
Legacy default number of approvals required before merge.
fallback_approvals_required integer
Approvals required when no approval rule applies.
prevent_merge_without_jira_issue boolean
Require an associated Jira issue before merging.
auto_duo_code_review_enabled boolean
Automatically request a GitLab Duo review on merge requests.
merge_pipelines_enabled boolean
Enable merged-results pipelines.
merge_trains_enabled boolean
Enable merge trains.
merge_trains_skip_train_allowed boolean
Allow a merge-train merge request to merge without waiting for its train pipeline.
merge_train_enforcement string
Can be one of: allow_bypass, enforce_for_all_users, enforce_with_owner_override.
max_pipelines_per_merge_train integer
Maximum parallel pipelines in the project's merge train.
security_policy_pipeline_must_succeed boolean
Require every security-policy pipeline to succeed before merging.
reviewer_assignment_strategy string
Automatic reviewer strategy. Can be one of: disabled, code_owners, dap_powered.
|
Example:
gitlab_settings_projects:
- path: platform/service
merge_requests:
merge_method: ff
...
|
|
repository object
Repository behavior. Scalar keys flatten into the project update.
Properties of repository
default_branch string
Default branch of the project.
lfs_enabled boolean
Enable Git Large File Storage for the repository.
repository_access_level string
Repository access. Can be one of: disabled, private, enabled.
repository_storage string
Storage shard that hosts the repository. Administrator-only.
import_url string
URL from which GitLab imports repository content.
web_based_commit_signing_enabled boolean
Sign commits created through the GitLab web interface.
|
Example:
gitlab_settings_projects:
- path: platform/service
repository:
lfs_enabled: true
...
|
|
ci_cd object
Pipeline and runner policy. Scalar keys flatten into the project update.
Properties of ci_cd
build_git_strategy string
Runner checkout strategy. Can be one of: fetch, clone.
build_timeout integer
Job timeout in seconds.
auto_cancel_pending_pipelines string
Auto-cancel redundant pending pipelines. Can be one of: disabled, enabled.
ci_config_path string
Path or external location of the CI/CD configuration file.
public_jobs boolean
Allow non-members to view public pipelines and jobs.
shared_runners_enabled boolean
Enable instance runners for the project.
group_runners_enabled boolean
Enable group runners for the project.
resource_group_default_process_mode string
Default resource-group queue mode. Can be one of: unordered, oldest_first, newest_first, newest_ready_first.
auto_devops_enabled boolean
Enable Auto DevOps.
auto_devops_deploy_strategy string
Auto Deploy strategy. Can be one of: continuous, manual, timed_incremental.
ci_default_git_depth integer
Default shallow-clone depth for CI/CD jobs.
keep_latest_artifact boolean
Keep artifacts from the latest successful job on each ref.
ci_forward_deployment_enabled boolean
Prevent older, still-pending deployment jobs from running after a newer deployment.
ci_forward_deployment_rollback_allowed boolean
Allow retries of older deployment jobs for rollbacks.
ci_allow_fork_pipelines_to_run_in_parent_project boolean
Allow fork merge-request pipelines to run in the parent project.
ci_separated_caches boolean
Separate CI/CD caches according to branch protection.
restrict_user_defined_variables boolean
Restrict user-defined variables supplied when a pipeline starts.
ci_pipeline_variables_minimum_override_role string
Minimum role allowed to override pipeline variables. Can be one of: no_one_allowed, developer, maintainer, owner.
ci_push_repository_for_job_token_allowed boolean
Allow this project's CI/CD job tokens to push to its repository.
ci_delete_pipelines_in_seconds integer
Delete pipelines older than this many seconds.
max_artifacts_size integer
Maximum size in megabytes for an individual job artifact.
protect_merge_request_pipelines boolean
Make protected variables and runners available to merge-request pipelines.
ci_display_pipeline_variables boolean
Display manually defined variables on pipeline details pages.
allow_pipeline_trigger_approve_deployment boolean
Allow the pipeline triggerer to approve deployments.
ci_restrict_pipeline_cancellation_role string
Role policy controlling who may cancel pipelines and jobs.
|
Example:
gitlab_settings_projects:
- path: platform/service
ci_cd:
build_timeout: 3600
...
|
|
packages_and_registry object
Package and registry policy. Scalar keys flatten into the project update.
Properties of packages_and_registry
package_registry_access_level string
Package registry access. Can be one of: disabled, private, enabled, public.
container_registry_access_level string
Container registry access. Can be one of: disabled, private, enabled.
|
Example:
gitlab_settings_projects:
- path: platform/service
packages_and_registry:
package_registry_access_level: enabled
...
|
|
service_desk object
Service Desk settings. Scalar keys flatten into the project update.
Properties of service_desk
service_desk_enabled boolean
Enable Service Desk for the project.
|
Example:
gitlab_settings_projects:
- path: platform/service
service_desk:
service_desk_enabled: false
...
|
|
forking object
Fork policy. Scalar keys flatten into the project update.
Properties of forking
forking_access_level string
Fork access. Can be one of: disabled, private, enabled.
mr_default_target_self boolean
Make merge requests from this fork target the fork itself by default.
|
Example:
gitlab_settings_projects:
- path: platform/service
forking:
forking_access_level: enabled
...
|
|
housekeeping object
Reserved organizational section for future project housekeeping settings.
Properties of housekeeping
GitLab's project-edit endpoint defines no housekeeping property.
|
Example: none — omit this section.
|
|
compliance object
Project compliance attributes. Scalar keys flatten into the project update.
Properties of compliance
security_and_compliance_access_level string
Security and compliance feature access. Can be one of: disabled, private, enabled.
external_authorization_classification_label string
External authorization classification label assigned to the project.
enforce_auth_checks_on_uploads boolean
Require authorization checks when users access uploaded files.
spp_repository_pipeline_access boolean
Grant linked CI/CD projects read-only access to security-policy configuration.
|
Example:
gitlab_settings_projects:
- path: platform/service
compliance:
security_and_compliance_access_level: private
...
|
|
hooks array of objects
Project webhooks. Same schema and lifecycle as System Hooks, including write-only secrets, url_variables, and custom_headers.
Properties of hooks
id integer
Optional lookup-only identity for one existing hook.
name string
Preferred hook identity. When id is omitted, declare name or url.
url stringRequired on create
Private destination URL and fallback identity.
description string
state string
Can be one of: present, absent. Default: present.
token string
Write-only shared secret.
signing_token string
Write-only HMAC signing secret in GitLab's whsec_* format.
force_secret_update boolean
Rewrite declared secrets even when no readable property drifted.
enable_ssl_verification boolean
push_events boolean
push_events_branch_filter string
branch_filter_strategy string
Can be one of: wildcard, regex, all_branches.
issues_events boolean
confidential_issues_events boolean
merge_requests_events boolean
tag_push_events boolean
note_events boolean
confidential_note_events boolean
job_events boolean
pipeline_events boolean
wiki_page_events boolean
deployment_events boolean
feature_flag_events boolean
releases_events boolean
milestone_events boolean
emoji_events boolean
resource_access_token_events boolean
resource_deploy_token_events boolean
vulnerability_events boolean
custom_webhook_template string
url_variables object or array
Write-only URL variables in map form, map-with-state form, or {key, value, state} list form.
Properties of each url_variables entry
key stringRequired in list form
Child identity. In map form, the map key supplies it.
value stringRequired when state is present
Write-only value. It is required when this entry's state is present (the default). Omit it when state: absent; deletion uses the entry's key.
force_secret_update boolean
Rewrite the value when no readable child attribute drifted. Default: false.
state string
Can be one of: present, absent. Default: present.
custom_headers object or array
Write-only custom headers in map form, map-with-state form, or {key, value, state} list form.
Properties of each custom_headers entry
key stringRequired in list form
Child identity. In map form, the map key supplies it.
value stringRequired when state is present
Write-only value. It is required when this entry's state is present (the default). Omit it when state: absent; deletion uses the entry's key.
force_secret_update boolean
Rewrite the value when no readable child attribute drifted. Default: false.
state string
Can be one of: present, absent. Default: present.
|
Example:
gitlab_settings_projects:
- path: platform/service
hooks:
- name: service-events
url: https://hooks.example.com/gitlab/projects/service
pipeline_events: true
...
|
|
push_rules object
The project's singleton push rule; same semantics and fields as the group form in Group Settings, including state: absent.
Properties of push_rules
author_email_regex string
Regular expression that commit author email addresses must match.
branch_name_regex string
Regular expression that branch names must match.
commit_committer_check boolean
Require the committer to be a GitLab member.
commit_committer_name_check boolean
Require the committer name to match the user's GitLab name.
commit_message_negative_regex string
Reject commit messages matching this regular expression.
commit_message_regex string
Require commit messages to match this regular expression.
deny_delete_tag boolean
Prevent users from deleting Git tags.
file_name_regex string
Reject files whose paths match this regular expression.
max_file_size integer
Maximum size in megabytes for a pushed file; 0 disables the limit.
member_check boolean
Restrict pushes to verified GitLab users.
prevent_secrets boolean
Reject commits that GitLab detects as containing secrets.
reject_non_dco_commits boolean
Reject commits without a Developer Certificate of Origin sign-off.
reject_unsigned_commits boolean
Reject commits without a verified cryptographic signature.
state string
Can be one of: present, absent. Default: present.
|
Example:
gitlab_settings_projects:
- path: platform/service
push_rules:
reject_unsigned_commits: true
reject_non_dco_commits: true
...
|
|
protected_branches array of objects
Protected branch rules matched by name. Entry schema, access levels, and the access-array caveat are documented in Group Settings. Project-level rules support in-place scalar updates (via PATCH) on both backends' API path; the Rails backend creates missing rules and treats existing ones as in sync.
Properties of protected_branches
name stringRequired
Branch name or wildcard and rule identity.
allowed_to_push array of objects
Push access entries of {access_level: <level>}.
allowed_to_merge array of objects
Merge access entries of {access_level: <level>}.
allowed_to_unprotect array of objects
Access entries allowed to unprotect the branch.
Properties of each protected-branch access entry
access_level string or integerRequired
Can be one of: no_access (0), guest (10), reporter (20), developer (30), maintainer (40), owner (50), admin (60). Unknown names fail planning.
allow_force_push boolean
code_owner_approval_required boolean
state string
Can be one of: present, absent. Default: present.
|
Example:
gitlab_settings_projects:
- path: platform/service
protected_branches:
- name: main
allowed_to_push:
- access_level: maintainer
code_owner_approval_required: true
...
|
|
protected_tags array of objects
Protected tag rules matched by name, including wildcard names.
Properties of protected_tags
name stringRequired
Tag name or wildcard and rule identity.
allowed_to_create array of objects
Access entries allowed to create matching tags.
Properties of each allowed_to_create entry
access_level string or integerRequired
Can be one of: no_access (0), guest (10), reporter (20), developer (30), maintainer (40), owner (50), admin (60). Unknown names fail planning.
state string
Can be one of: present, absent. Default: present
Note: GitLab cannot update a protected tag in place; drift on an existing rule fails in strict mode and is recorded as a skip in compatible mode. Remove and re-add the rule to change it.
|
Example:
gitlab_settings_projects:
- path: platform/service
protected_tags:
- name: "v*"
allowed_to_create:
- access_level: maintainer
...
|
|
approvals object
Merge-request approval configuration. Requires the api backend; selecting Rails fails in strict mode or records skips in compatible mode.
Properties of approvals
settings object
Project-wide merge-request approval settings.
Properties of approvals.settings
allow_author_approval boolean
allow_committer_approval boolean
allow_overrides_to_approver_list_per_merge_request boolean
require_password_to_approve boolean
require_reauthentication_to_approve boolean
retain_approvals_on_push boolean
selective_code_owner_removals boolean
rules array of objects
Approval rules matched by name. Scalar fields reconcile with drift detection; approver arrays apply on create but are excluded from drift detection.
Properties of approvals.rules
name stringRequired
approvals_required integerRequired on create
applies_to_all_protected_branches boolean
coverage_minimum_threshold number
report_type string
rule_type string
scanners array of strings
severity_levels array of strings
user_ids array of integers
Applied on create and excluded from drift detection.
usernames array of strings
group_ids array of integers
Applied on create and excluded from drift detection.
protected_branch_ids array of integers
Applied on create and excluded from drift detection.
vulnerabilities_allowed integer
vulnerability_states array of strings
|
Example:
gitlab_settings_projects:
- path: platform/service
approvals:
settings:
allow_author_approval: false
rules:
- name: security-review
approvals_required: 2
...
|
|
custom_attributes object
Custom attribute key/value pairs; same semantics as the group form.
Properties of custom_attributes
<attribute name> string
The map key is the custom-attribute identity; the value must be bounded text.
|
Example:
gitlab_settings_projects:
- path: platform/service
custom_attributes:
managed_by: ansible
...
|
|
external_status_checks array of objects
External status check services that merge requests must pass, matched by name.
Properties of external_status_checks
name stringRequired
Service name and identity.
external_url stringRequired on create
Service URL; reconciles by private fingerprint.
protected_branch_ids array of integers
Protected branches to which the service applies; reconciles with drift detection.
shared_secret string
Write-only secret carried on every write and never displayed or diffed.
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_projects:
- path: platform/service
external_status_checks:
- name: compliance-gate
external_url: https://checks.example.com/gitlab
shared_secret: "{{ vault_status_check_secret }}"
...
|
|
feature_flags array of objects
Project feature flags matched by name. GitLab sets version on create; it is not managed.
Properties of feature_flags
name stringRequired
Feature-flag name and identity.
active boolean
Desired live state; reconciles with drift detection.
description string
Feature-flag description; reconciles with drift detection.
strategies array of objects
Nested rollout configuration. Applied on create and not compared or updated afterward.
Properties of each strategies entry
name stringRequired
Can be one of: default, gradualRolloutUserId, userWithId, gitlabUserList, flexibleRollout.
parameters object
Strategy-specific string parameters.
Common properties of parameters
percentage string
Rollout percentage used by gradual or flexible rollout strategies.
group_id string
Group identifier used by the gradual rollout strategy.
userIds string
Comma-separated user IDs used by the user-targeting strategy.
user_list_id integer
Feature-flag user-list ID for the gitlabUserList strategy.
scopes array of objects
Environment scopes in which the strategy applies.
Properties of each strategies[].scopes entry
environment_scope stringRequired
Environment name or wildcard matched by this scope.
state string
Can be one of: present, absent. Default: present
Note — declared state wins: a declared active value is applied on every run and overwrites live toggles made in the UI. This is the project feature-flag surface, distinct from the instance features gates.
|
Example:
gitlab_settings_projects:
- path: platform/service
feature_flags:
- name: beta_ui
active: true
description: Roll out the redesigned UI
strategies:
- name: gradualRolloutUserId
parameters:
percentage: "25"
group_id: default
...
|
|
security_policies object
The project's security policies as one document. This surface is GraphQL-only (backends: [graphql]) and converge-only: the project must already be linked to a Security Policy Project. Idempotence is by parsed policy name within each array, so reordering and whitespace never trigger a commit; per-policy state: absent prunes that policy.
Properties of security_policies
scan_execution_policy array of policy objects
Policies that run security scanners on schedules or other declared conditions.
pipeline_execution_policy array of policy objects
Policies that inject or enforce CI/CD pipeline configuration.
pipeline_execution_schedule_policy array of policy objects
Policies that schedule execution of security-policy pipelines.
vulnerability_management_policy array of policy objects
Policies that automate vulnerability-management actions.
approval_policy array of policy objects
Generates report_approver rules; this is distinct from classic approvals.rules.
Common properties of each security-policy object
name stringRequired
Policy identity. Names must be unique within their parent policy array.
state string
Lifecycle state. Can be one of: present, absent. Default: present.
type string
Optional explicit type. When declared, it must exactly equal the parent array name.
enabled, rules, actions, and other policy-specific keys YAML values
Every string-keyed policy field and nested value is preserved, then GitLab validates the fields for the selected policy type. Null values are omitted; aliases, duplicate keys, non-string keys, and declarations beyond the documented size, depth, and node budgets fail before mutation.
An existing linked Security Policy Project is required; this surface does not create that link.
Ownership modes: the default (mode: replace) is a full-replace target — policies authored outside this declaration in the same .gitlab/security-policies/policy.yml are pruned, and an undeclared policy array is emptied; declare every policy you want to keep. mode: merge co-owns the document instead: foreign policies and undeclared arrays are preserved, removal happens only through a per-policy state: absent, and the diff reports managed names only (mode: merge cannot combine with document-level state: absent). In both modes GitLab accepts exactly one named policy per commit mutation, so each changed policy uses one APPEND, REPLACE, or REMOVE. These mutations are sequential, not transactional: a later failure can leave earlier changes applied, and a corrected rerun converges the remainder.
Note — async propagation and normalization: real GitLab does not reflect a policy commit immediately (~10 minutes), so a second run against a live instance may still report drift until propagation completes. Idempotence is verified offline; against a live instance, GitLab may also normalize or inject defaults into stored policies, so treat repeated no-op runs as best-effort until confirmed on your instance. A malformed declaration (a mapping instead of a list of policies, an entry with no name, a duplicate name, or a conflicting type) fails the run loudly before any mutation rather than silently pruning.
The classic per-project MR approval rules managed over REST (approvals.rules) are a different feature from approval_policy here, which generates report_approver rules; avoid managing overlapping approval configuration through both.
|
Example:
gitlab_settings_projects:
- path: platform/service
security_policies:
scan_execution_policy:
- name: nightly-sast
enabled: true
rules:
- type: schedule
cadence: "0 2 * * *"
actions:
- scan: sast
approval_policy:
- name: require-security-approval
enabled: true
...
|
|
escalation_policies array of objects
Incident-management escalation policies managed through the GraphQL-only backend (backends: [graphql]). GitLab's nested response is normalized back to the flat declaration shape for exact second-run comparison.
Properties of escalation_policies
name stringRequired
Escalation-policy name and identity.
description string
Policy description; reconciles with drift detection.
rules array of objectsRequired on create
Ordered replace-all rule list.
Properties of escalation_policies[].rules
username stringRequired unless alternate target is set
Existing user target. Declare exactly one of username or oncall_schedule_iid.
oncall_schedule_iid string or integerRequired unless alternate target is set
Explicitly known IID of an existing on-call schedule. A newly created schedule name is not translated to its server-assigned IID.
status stringRequired
Target incident status, such as ACKNOWLEDGED or RESOLVED.
elapsed_time_seconds integerRequired
Delay before this escalation rule applies.
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_projects:
- path: platform/service
escalation_policies:
- name: primary-escalation
rules:
- username: oncall-engineer
status: ACKNOWLEDGED
elapsed_time_seconds: 300
...
|
|
runners array of objects
Project runners registered through the GitLab 16+ user-runner endpoint. The declared project is resolved to its numeric id automatically, the one-time authentication token is captured exactly once to token_file (mode 0600), and comparison reads the runner-detail endpoint. The convergence listing is scoped to this project and filtered to project_type, so inherited or shared runners are never claimed.
Properties of runners
description stringRequired
Runner description and identity.
token_file string
Absolute controller path capturing the one-time authentication token.
tag_list array of strings
paused boolean
locked boolean
run_untagged boolean
access_level string
Can be one of: not_protected, ref_protected.
maintenance_note string
maximum_timeout integer
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_projects:
- path: platform/service
runners:
- description: project-runner
token_file: /var/lib/ansible/secrets/project-runner-token
run_untagged: true
...
|
|
oncall_schedules array of objects
Incident-management on-call schedules managed through the GraphQL-only backend (backends: [graphql]). Declared rotation times compare in the schedule's timezone against GitLab's UTC timestamps.
Properties of oncall_schedules
name stringRequired
Schedule name and identity.
description string
Schedule description; reconciles with drift detection.
timezone stringRequired on create
IANA timezone; reconciles with drift detection.
rotations array of objects
Nested rotations matched by name. Their full configuration reconciles through create, update, and delete mutations.
Properties of oncall_schedules[].rotations
name stringRequired
starts_at objectRequired on create
Required on create; local start timestamp in the schedule's timezone.
Properties of starts_at
date string (date)Required
Calendar date in YYYY-MM-DD form.
time string (time)Required
24-hour time in HH:MM form.
ends_at object
Optional local end timestamp in the schedule's timezone.
Properties of ends_at
date string (date)Required
Calendar date in YYYY-MM-DD form.
time string (time)Required
24-hour time in HH:MM form.
rotation_length objectRequired on create
Required on create; duration assigned to each participant before rotating.
Properties of rotation_length
length integerRequired
Positive duration amount.
unit stringRequired
Can be one of: HOURS, DAYS, WEEKS.
active_period object
Optional daily active window.
Properties of active_period
start_time string (time)Required
Window start in 24-hour HH:MM form.
end_time string (time)Required
Window end in 24-hour HH:MM form.
participants array of objectsRequired on create
Required on create; the ordered list must contain between 1 and 100 unique usernames.
Properties of each participants entry
username stringRequired
Existing GitLab username. Duplicate usernames fail planning.
color_palette string
GitLab display-color palette. The value is normalized to uppercase before submission. Default: blue.
color_weight string or integer
GitLab display-color weight. A numeric value is normalized to WEIGHT_<value>. Default: 500.
state string
Can be one of: present, absent. Default: present
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_projects:
- path: platform/service
oncall_schedules:
- name: primary
timezone: Etc/UTC
rotations:
- name: weekly
starts_at: {date: "2026-01-01", time: "09:00"}
rotation_length: {length: 1, unit: WEEKS}
participants:
- username: oncall-engineer
...
|
|
feature_flag_user_lists array of objects
Named user lists that feature-flag strategies target. Lists are matched by name and routed for update and delete by their server-assigned iid.
Properties of feature_flag_user_lists
name stringRequired
User-list name and identity.
user_xids stringRequired on create
Comma-separated external user ids; reconciles with drift detection.
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_projects:
- path: platform/service
feature_flag_user_lists:
- name: beta_testers
user_xids: "1001,1002,1003"
...
|
Deployment surfaces (environments, protected environments, deploy keys,
pipeline schedules, registry/package/tag protection rules, freeze periods)
are documented in
Environments and Deployments.