Groups are created from their declarations
A declared group that does not exist is created: the last path segment
becomes its path and name, and a nested group resolves its parent
through the API. Declaration order is the dependency order -- declare a
parent group (or a share partner) before anything that references it. A
group and all of its children -- hooks, members, variables, labels, shares,
push rules, and the GraphQL-backed surfaces such as custom emoji -- apply
together in one run: each child records a dependency on its container's
create operation, which the write gate's check-mode preflight accepts in
place of live state, and the transport partitions apply in an order that
creates containers before their children. A bare entry (just a path,
or a path with only children) still creates the group when it is
missing, and a declared name wins over the derived last path segment.
An entry may declare state: absent — alone; an absent container cannot
also declare settings or children — to delete the group, and the public
gitlab_settings task offers the same via resource: group with
state: absent. Deletion removes everything inside the group. On
instances with delayed deletion GitLab marks the group and frees its
path by renaming it; the old path's route-history redirect is treated
as absence, so repeating the deletion is idempotent and the
path is immediately reusable.
The nine setting objects below are organizational sections. Their scalar
properties are flattened into one PUT /groups/:id request, so declare each
property in only one section. The fields below describe the scalar properties
accepted by GitLab's group-update endpoint; the section placement is the
recommended grouping used throughout these examples.
Structured GitLab group-update properties
GitLab also defines the following object and array properties. They are listed separately from the scalar organizational sections below.
default_branch_protection_defaults object
Default access rules for a group's default branch.
Properties of default_branch_protection_defaults
allowed_to_push array of objects
Access levels allowed to push to the default branch.
Properties of each allowed_to_push entry
access_level integerRequired
Can be one of: 0 (no access), 30 (Developer), 40 (Maintainer), or 60 (Administrator).
allowed_to_merge array of objects
Access levels allowed to merge into the default branch.
Properties of each allowed_to_merge entry
access_level integerRequired
Can be one of: 0 (no access), 30 (Developer), 40 (Maintainer), or 60 (Administrator).
allow_force_push boolean
Allow force pushes by users who have push access.
code_owner_approval_required boolean
Require approval from Code Owners.
developer_can_initial_push boolean
Allow a Developer to make the initial push to an empty repository.
ai_settings_attributes object
Duo Agent Platform settings.
Properties of ai_settings_attributes
duo_agent_platform_enabled boolean
Enable Duo Agent Platform features.
duo_workflow_mcp_enabled boolean
Enable Model Context Protocol support for Duo Agent Platform.
ai_usage_data_collection_enabled boolean
Enable AI usage-data collection for the namespace.
ai_catalog_restricted_to_group_hierarchy boolean
Restrict the AI Catalog to items within this top-level group hierarchy.
foundational_agents_default_enabled boolean
Enable new foundational agents by default.
prompt_injection_protection_level string
Can be one of: no_checks, log_only, or interrupt.
include_recommended_allowed boolean
Include recommended domains in the network-access allowlist.
allow_all_unix_sockets boolean
Allow all Unix sockets for network access.
allow_project_extension boolean
Allow projects to extend the network-access domain allowlist.
minimum_access_level_execute integer
Minimum access level required to execute Duo Agent Platform. Can be one of: 10, 15, 20, 30, 40, or 50.
minimum_access_level_execute_async integer
Minimum access level required to execute Duo Agent Platform features in CI/CD. Can be one of: 30, 40, or 50.
minimum_access_level_manage integer
Minimum access level required to manage Duo Agent Platform. Can be one of: 30, 40, or 50.
minimum_access_level_enable_on_projects integer
Minimum access level required to enable Duo Agent Platform on projects. Can be one of: 30, 40, or 50.
duo_namespace_access_rules array of objects
Duo feature-access rules.
Properties of each duo_namespace_access_rules entry
through_namespace object
Namespace through which feature access is granted.
Properties of through_namespace
id integerRequired
Namespace ID.
name string
Namespace name.
full_path string
Full namespace path.
features array of stringsRequired
Duo features accessible through the namespace.
enabled_foundational_flows array of strings
References of enabled foundational flows.
foundational_agents_statuses array of objects
Enabled state for individual foundational agents.
Properties of each foundational_agents_statuses entry
reference stringRequired
Foundational-agent reference.
enabled booleanRequired
Whether the foundational agent is enabled.
unique_project_download_limit_allowlist array of strings
Usernames excluded from the unique-project download limit.
unique_project_download_limit_alertlist array of integers
User IDs notified when the unique-project download limit is exceeded.
|
path string Required
Full path of the group, including any parent groups.
|
Example:
gitlab_settings_groups:
- path: platform/engineering
...
|
|
group object
Visibility, description, and general group attributes. Scalar keys flatten into the group update.
Properties of group
name string
Display name of the group.
path string
URL path of the group. The entry's top-level path remains the lookup identity for the current run.
description string
Description shown on the group's overview page.
visibility string
Can be one of: private, internal, public.
avatar string (binary file)
Avatar image uploaded for the group. An empty value removes the current avatar.
request_access_enabled boolean
Allow users to request membership in the group.
|
Example:
gitlab_settings_groups:
- path: platform
group:
visibility: private
...
|
|
permissions object
Creation levels and access controls. Scalar keys flatten into the group update.
Properties of permissions
project_creation_level string
Minimum role allowed to create projects. Can be one of: noone, owner, maintainer, developer, administrator.
subgroup_creation_level string
Minimum role allowed to create subgroups. Can be one of: owner, maintainer.
enabled_git_access_protocol string
Protocols allowed for Git access. Can be one of: ssh, http, all.
membership_lock boolean
Prevent users from being added directly to projects within the group.
share_with_group_lock boolean
Prevent projects in this group from being shared with another group.
prevent_sharing_groups_outside_hierarchy boolean
Prevent sharing groups in this namespace with groups outside its hierarchy. Available only on top-level groups.
allowed_email_domains_list string
Comma-separated email domains whose users may access the group.
ip_restriction_ranges string
Comma-separated IP addresses or subnet masks allowed to access the group.
ldap_cn string
LDAP common name associated with the group.
ldap_access integer
GitLab access level assigned through the group's LDAP association.
step_up_auth_required_oauth_provider string
OAuth provider required for step-up authentication. Use an empty string to disable it.
allow_personal_snippets boolean
Allow enterprise users in the group to create snippets in their personal namespaces.
|
Example:
gitlab_settings_groups:
- path: platform
permissions:
project_creation_level: maintainer
...
|
|
project_defaults object
Defaults inherited by projects. Scalar keys flatten into the group update.
Properties of project_defaults
auto_devops_enabled boolean
Enable Auto DevOps by default for projects in the group.
default_branch string
Default branch name used when projects are created in the group.
default_branch_protection integer
Deprecated default-branch protection level. Can be one of: 0 (not protected), 1 (partial), 2 (fully protected), 3 (protected against pushes), 4 (fully protected after the initial push).
shared_runners_setting string
Instance-runner policy inherited by subgroups and projects. Can be one of: enabled, disabled_and_overridable, disabled_and_unoverridable.
shared_runners_minutes_limit integer
Administrator-managed monthly compute-minute limit. 0 means unlimited.
extra_shared_runners_minutes_limit integer
Administrator-managed additional compute minutes for the group.
max_artifacts_size integer
Maximum size in megabytes for an individual job artifact.
web_based_commit_signing_enabled boolean
Enable signing for commits created through the GitLab web interface. Available only for top-level groups on GitLab.com.
|
Example:
gitlab_settings_groups:
- path: platform
project_defaults:
default_branch: main
shared_runners_setting: disabled_and_overridable
...
|
|
merge_requests object
Merge-request behavior. Scalar keys flatten into the group update.
Properties of merge_requests
only_allow_merge_if_pipeline_succeeds boolean
Require a successful pipeline before a merge request can be merged. When enabled at group level, the requirement applies to every project in the group.
allow_merge_on_skipped_pipeline boolean
Treat a skipped pipeline as satisfying the successful-pipeline requirement. This has an effect only when only_allow_merge_if_pipeline_succeeds is enabled.
only_allow_merge_if_all_discussions_are_resolved boolean
Require every merge-request discussion to be resolved before merging. When enabled at group level, the requirement applies to every project in the group.
show_diff_preview_in_email boolean
Include code-diff previews in merge-request notification emails.
|
Example:
gitlab_settings_groups:
- path: platform
merge_requests:
only_allow_merge_if_pipeline_succeeds: true
allow_merge_on_skipped_pipeline: false
only_allow_merge_if_all_discussions_are_resolved: true
...
|
|
duo object
GitLab Duo controls. Scalar keys flatten into the group update.
Properties of duo
duo_availability string
Default GitLab Duo availability. Can be one of: default_on, default_off, never_on, always_on.
duo_features_enabled boolean
Enable GitLab Duo features for the group.
lock_duo_features_enabled boolean
Enforce the group's Duo feature setting for all subgroups.
duo_core_features_enabled boolean
Enable experimental GitLab Duo Core features for the group.
duo_remote_flows_availability boolean
Enable GitLab Duo remote flows for the group.
duo_foundational_flows_availability boolean
Enable GitLab Duo foundational flows for the group.
duo_custom_agents_availability boolean
Enable GitLab Duo custom agents for the group.
duo_custom_flows_availability boolean
Enable GitLab Duo custom flows for the group.
duo_external_agents_availability boolean
Enable GitLab Duo external agents for the group.
tool_approval_for_session_availability string
Availability of tool approval for a Duo session. Can be one of: default_on, default_off, never_on.
auto_duo_code_review_enabled boolean
Automatically request a GitLab Duo review on merge requests.
amazon_q_auto_review_enabled boolean
Automatically request an Amazon Q review on merge requests.
duo_template_project_id integer
Project ID containing custom instructions for GitLab Duo Code Review.
model_prompt_cache_enabled boolean
Enable model prompt caching for the group.
create_code_review_flow_consent boolean
Record explicit namespace consent for routing Code Review through the Duo Agent Platform.
|
Example:
gitlab_settings_groups:
- path: platform
duo:
duo_features_enabled: false
lock_duo_features_enabled: true
...
|
|
security_and_compliance object
Security and compliance policy. Scalar keys flatten into the group update.
Properties of security_and_compliance
require_two_factor_authentication boolean
Require every group member to configure two-factor authentication.
two_factor_grace_period integer
Number of hours members have to configure two-factor authentication before enforcement.
prevent_forking_outside_group boolean
Prevent projects in the group from being forked to an external namespace.
resource_access_token_notify_inherited boolean
Send resource-access-token expiry notifications to inherited group members.
lock_resource_access_token_notify_inherited boolean
Prevent subgroups from overriding inherited-member token expiry notifications.
service_access_tokens_expiration_enforced boolean
Enforce access-token expiration for service-account users in the group.
unique_project_download_limit integer
Maximum unique projects a user may download during the configured interval before Git abuse controls apply. Available only on top-level groups.
unique_project_download_limit_interval_in_seconds integer
Time window, in seconds, used by unique_project_download_limit.
auto_ban_user_on_excessive_projects_download boolean
Ban users from the group when they exceed the unique-project download limit.
|
Example:
gitlab_settings_groups:
- path: platform
security_and_compliance:
require_two_factor_authentication: true
two_factor_grace_period: 48
prevent_forking_outside_group: true
...
|
|
features object
Group feature availability. Scalar keys flatten into the group update.
Properties of features
crm_enabled boolean
Enable Customer Relations Management for the group.
emails_enabled boolean
Enable email notifications for the group.
mentions_disabled boolean
Disable mentioning the group.
lfs_enabled boolean
Enable Git Large File Storage for projects in the group.
wiki_access_level string
Group wiki availability. Can be one of: disabled, private, enabled.
experiment_features_enabled boolean
Enable experimental features for the group.
math_rendering_limits_enabled boolean
Apply math-rendering limits to the group.
lock_math_rendering_limits_enabled boolean
Enforce the math-rendering limit setting for every descendant group.
|
Example:
gitlab_settings_groups:
- path: platform
features:
emails_enabled: false
lfs_enabled: true
...
|
|
templates object
Template sources. Scalar keys flatten into the group update.
Properties of templates
file_template_project_id integer
Project ID from which GitLab loads custom file templates.
built_in_project_templates_enabled boolean
Offer GitLab's built-in project templates when users create projects in the group.
lock_built_in_project_templates_enabled boolean
Enforce the built-in project-template setting for every subgroup.
|
Example:
gitlab_settings_groups:
- path: platform
templates:
file_template_project_id: 42
...
|
|
packages_and_registry object
Reserved organizational section for future package and registry settings.
Properties of packages_and_registry
GitLab's group-update endpoint defines no package or registry property. For example, packages_enabled is not accepted by this endpoint.
|
Example: none — omit this section.
|
|
hooks array of objects
Group 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
project_events boolean
wiki_page_events boolean
deployment_events boolean
feature_flag_events boolean
releases_events boolean
milestone_events boolean
subgroup_events boolean
emoji_events boolean
resource_access_token_events boolean
member_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_groups:
- path: platform
hooks:
- name: group-audit
url: https://hooks.example.com/gitlab/group
push_events: true
...
|
|
push_rules object
The group's singleton push rule. Created when missing, updated when drifted, and removable.
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_groups:
- path: platform
push_rules:
reject_unsigned_commits: true
prevent_secrets: true
- path: platform/sandbox
push_rules:
state: absent
...
|
|
protected_branches array of objects
Group-level protected branch rules, matched by name.
Properties of a protected branch entry
name string Required
Branch name or wildcard, such as main or release/*.
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
Note: access arrays do not round-trip through the API in request shape, so they apply on create but are excluded from drift detection and updates. Group protected branches require the api backend; selecting Rails fails in strict mode or records skips in compatible mode.
|
Example:
gitlab_settings_groups:
- path: platform
protected_branches:
- name: main
allowed_to_push:
- access_level: maintainer
allowed_to_merge:
- access_level: developer
allow_force_push: false
...
|
|
custom_attributes object
Custom attribute key/value pairs. Values are stored by GitLab as strings; each declared key is created or updated to match.
Properties of custom_attributes
<attribute name> string
The map key is the custom-attribute identity; the value must be bounded text.
|
Example:
gitlab_settings_groups:
- path: platform
custom_attributes:
managed_by: ansible
cost_center: eng-042
...
|
|
saml_provider object
The group's SAML SSO provider (GitLab SaaS groups and self-managed with group SAML). This surface has no REST or GraphQL endpoint — it is an ActiveRecord model — so it is Rails-only: it applies only when the rails transport is in your gitlab_settings_backend preference (rails or all). Under the default api preset, strict mode fails because the required transport is omitted; compatible mode records an actionable skip.
Authority: a group access token cannot constrain this operation because Rails does not use API authentication. Apply it only from an instance-authoritative SSH or Kubernetes execution identity, in a separate invocation from a group-scoped persona.
Properties of saml_provider
enabled boolean
sso_url string
certificate_fingerprint string
Public certificate fingerprint; not treated as a secret.
default_membership_role string or integer
enforced_sso boolean
git_check_enforced boolean
enforced_group_managed_accounts boolean
prohibited_outer_forks boolean
Note: this is the group SSO provider only. Instance SAML is boot-time deployment configuration and is not available through this runtime API surface.
|
Example:
gitlab_settings_backend: all # or rails
gitlab_settings_groups:
- path: platform
saml_provider:
enabled: true
sso_url: https://sso.example.com/saml
certificate_fingerprint: "0a:1b:2c:..."
enforced_sso: true
default_membership_role: developer
...
|
|
custom_emoji array of objects
Group custom emoji. This surface has no REST endpoint and is GraphQL-only (backends: [graphql]), so it applies under the default api preset.
Properties of custom_emoji
name stringRequired
Emoji name and identity.
url stringRequired on create
Emoji image URL. Set on create; a change converges through destroy and recreate because GitLab has no update mutation.
state string
Can be one of: present, absent. Default: present
Note — recreate is not atomic: GitLab offers no update mutation for custom emoji and enforces per-group name uniqueness (so a create cannot precede the destroy), leaving destroy-then-create the only way to change a url. If the create then fails, the run fails loudly and the emoji is absent until the next successful converge (self-healing for a valid desired state).
|
Example:
gitlab_settings_groups:
- path: platform
custom_emoji:
- name: shipit
url: https://example.com/emoji/shipit.png
...
|
|
compliance_frameworks array of objects
Group compliance frameworks, managed through the GraphQL-only backend (backends: [graphql]).
Properties of compliance_frameworks
name stringRequired
Framework name and identity.
description string
Framework description; reconciles with drift detection.
color string
Framework color; reconciles with drift detection.
default boolean
Whether this is the group's default framework. GitLab allows at most one default and clears the previous one when a new default is set.
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_groups:
- path: platform
compliance_frameworks:
- name: SOC2
description: SOC 2 controls
color: "#1f75cb"
default: true
...
|
|
value_streams array of objects
Value stream analytics definitions managed through the GraphQL-only backend (backends: [graphql]). Real GitLab may normalize stored stages, so stage drift comparison is best-effort against a live instance.
Properties of value_streams
name stringRequired
Value-stream name and identity.
stages array of objects
Nested stage list, replaced in full on update.
Properties of each stages entry
id string
Existing stage GraphQL id. Accepted only when updating a value stream; omit on create.
name stringRequired on create
Stage name. Required when creating a value stream. An update entry must provide id, name, or both.
custom boolean
Whether this is a custom stage.
hidden boolean
Whether to hide the stage from the value stream.
state string
Can be one of: present, absent. Default: present
|
Example:
gitlab_settings_groups:
- path: platform
value_streams:
- name: delivery
stages:
- name: issue
custom: false
...
|
|
work_item_types array of objects
Namespace work item types managed through the GraphQL-only backend (backends: [graphql]).
Properties of work_item_types
name stringRequired
Work-item type name and identity.
icon_name stringRequired on create
Icon name. Reconciles and is required when creating a custom type.
enabled boolean
Per-namespace availability (GitLab 19.1+; upstream marks the surface 18.11, but 18.11.7 lacks it — verified live). On older supported versions, a declaration using it fails with the server naming the missing surface. This is the one change the built-in lock guard admits, so built-ins (Issue, Incident, Task, …) can be enabled or disabled while other modifications remain unsupported. A newly created custom type converges a declared enabled: false in the same apply through a post-create toggle.
state string
Can be one of: present, absent. Default: present. absent archives a custom type through GitLab's update mutation; it is not a hard delete. Other mutation or archive attempts against built-ins fail in strict mode and skip in compatible mode.
|
Example:
gitlab_settings_groups:
- path: platform
work_item_types:
- name: Deployment
icon_name: rocket
...
|
|
runners array of objects
Group runners registered through the GitLab 16+ user-runner endpoint. The declared group 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 group and filtered to group_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_groups:
- path: platform
runners:
- description: group-runner
token_file: /var/lib/ansible/secrets/group-runner-token
run_untagged: true
...
|
|
dependency_proxy object
Group dependency proxy settings. This is a GraphQL-only update-only singleton (backends: [graphql]): it reconciles in place and supports no create or delete.
Properties of dependency_proxy
enabled boolean
Enable or disable the dependency proxy for the group.
Availability: the dependency proxy is an instance-level feature set in GitLab's deployment configuration (Helm chart deployments disable it by default). When it is disabled, GitLab exposes no settings object and refuses these mutations. See GitLab's dependency proxy administration docs.
|
Example:
gitlab_settings_groups:
- path: platform
dependency_proxy:
enabled: true
...
|
|
dependency_proxy_ttl_policy object
Image TTL cleanup policy for the group dependency proxy. This is a GraphQL-only update-only singleton (backends: [graphql]): it reconciles in place and supports no create or delete.
Properties of dependency_proxy_ttl_policy
enabled boolean
Enable or disable dependency-proxy image cleanup.
ttl integer
Image retention time in days.
Availability: this policy exists only when the instance dependency proxy is enabled; see Troubleshooting and GitLab's dependency proxy administration docs.
|
Example:
gitlab_settings_groups:
- path: platform
dependency_proxy_ttl_policy:
enabled: true
ttl: 30
...
|