Instance administration

Configuring instance administration

Instance-level administration surfaces beyond application settings, all under gitlab_settings_instance. These require an administrator token and the api backend. Selecting Rails for them fails in strict mode or records operation-bound skips in compatible mode.

Example instance administration definition

gitlab_settings_instance:
  appearance:
    title: Lab GitLab
    description: Managed by settings-as-code
  plan_limits:
    plan_name: default
    ci_pipeline_size: 500
  broadcast_messages:
    - message: Maintenance window Sunday 02:00 UTC
      theme: indigo
  ci_variables:
    - key: DEPLOY_TOKEN
      value: "{{ vault_deploy_token }}"
      protected: true
      masked: true
  topics:
    - name: platform
      description: Platform engineering projects
  features:
    - name: some_feature_flag
      value: true
  license:
    data: "{{ vault_gitlab_license_key }}"
  audit_event_destinations:
    - name: primary-siem
      destination_url: https://siem.example.com/gitlab
  applications:
    - name: grafana-oauth
      redirect_uri: https://grafana.example.com/login/gitlab
      scopes: read_user
      secret_file: /var/lib/secrets/grafana-oauth.secret
  member_roles:
    - name: security-auditor
      base_access_level: 20
      read_code: true
      read_vulnerability: true

Instance Administration Spec

GitLab API reference

GitLab's API documentation defines the fields for each surface:

1. Appearance API
2. Plan limits API
3. Broadcast messages API
4. Instance-level CI/CD variables API
5. Topics API
6. License API
7. Features API
8. Audit event streaming API

appearance object  Instance appearance settings. The writable fields are listed below. Properties of appearance  title string  description string  site_name string  header_message string  footer_message string  message_background_color string  message_font_color string  email_header_and_footer_enabled boolean  member_guidelines string  new_project_guidelines string  profile_image_guidelines string  logo string  header_logo string  favicon string  pwa_name string  pwa_short_name string  pwa_description string  pwa_icon string	Example: gitlab_settings_instance: appearance: title: Lab GitLab header_message: Managed by Ansible ...
plan_limits object  Limits for one GitLab plan. Properties of plan_limits  plan_name stringRequired Selects the plan being read and written and is never drift-compared.  ci_active_jobs integer  ci_instance_level_variables integer  ci_needs_size_limit integer  ci_pipeline_schedules integer  ci_pipeline_size integer  ci_project_subscriptions integer  ci_registered_group_runners integer  ci_registered_project_runners integer  conan_max_file_size integer  dotenv_size integer  dotenv_variables integer  enforcement_limit integer  generic_packages_max_file_size integer  helm_max_file_size integer  maven_max_file_size integer  max_pipelines_per_merge_train integer  notification_limit integer  npm_max_file_size integer  nuget_max_file_size integer  pipeline_hierarchy_size integer  pypi_max_file_size integer  storage_size_limit integer  terraform_module_max_file_size integer  web_hook_calls integer  web_hook_calls_low integer  web_hook_calls_mid integer	Example: gitlab_settings_instance: plan_limits: plan_name: default ci_pipeline_size: 500 ci_active_jobs: 1000 ...
broadcast_messages array of objects  Instance broadcast messages, matched by unique message text or an explicit server id. Properties of broadcast_messages  message stringRequired on create Natural identity when unique and required to create a message.  id integer Server-assigned lookup identity when duplicate message text exists. Lookup-only.  theme string  dismissable boolean  starts_at string (date-time)  ends_at string (date-time)  target_access_levels array of integers  target_path string  broadcast_type string  state string Can be one of: present, absent. Default: present	Example: gitlab_settings_instance: broadcast_messages: - message: Maintenance Sunday broadcast_type: banner - message: Old notice state: absent ...
ci_variables array of objects  Instance-level CI/CD variables matched by key. Properties of ci_variables  key stringRequired Variable name and identity.  value stringRequired when state is present Required when the variable's state is present (the default). Omit it when state: absent; deletion uses the variable's key. This write-only secret is never compared or shown and is carried on every write.  force_secret_update boolean Force a rotation write when no readable field drifted. Default: false  protected boolean  masked boolean  raw boolean  variable_type string Can be one of: env_var, file.  description string  state string Can be one of: present, absent. Default: present	Example: gitlab_settings_instance: ci_variables: - key: DEPLOY_TOKEN value: "{{ vault_deploy_token }}" protected: true masked: true - key: ROTATED_TOKEN value: "{{ new_value }}" force_secret_update: true ...
topics array of objects  Instance project topics matched by name. Avatar upload is out of scope. Properties of topics  name stringRequired Topic name and identity.  title stringRequired on create Topic title; reconciles with drift detection.  description string Topic description; reconciles with drift detection.  organization_id integer Optional organization association accepted by GitLab's Topics API.  state string Can be one of: present, absent. Default: present	Example: gitlab_settings_instance: topics: - name: platform title: Platform ...
features array of objects  Instance feature-flag gates matched by name. Properties of features  name stringRequired Feature-gate name and identity.  value boolean or numberRequired when state is present Required when the feature's state is present (the default). Omit it when state: absent, which deletes the gate by name. Boolean values compare against the on/off gate state; numeric values compare against percentage gates.  state string Can be one of: present, absent. Default: present. absent deletes the gate and restores GitLab's default.	Example: gitlab_settings_instance: features: - name: some_feature value: true - name: rollout_feature value: 25 ...
license object  The instance license. There is no update verb in GitLab's API. Properties of license  data stringRequired when state is present Required when the license's state is present (the default). Omit it when state: absent, which removes the active license. This license key is secret and write-only; GitLab never returns it, so an active license is treated as in sync.  force_update boolean Re-add the declared license over an active license. Default: false  state string Can be one of: present, absent. Default: present. absent removes the active license.	Example: gitlab_settings_instance: license: data: "{{ vault_gitlab_license_key }}" ...
audit_event_destinations array of objects  Instance HTTP audit event streaming destinations. GraphQL-only (backends: [graphql]); the group form in Labels, badges, and roles uses the same declaration shape. Properties of audit_event_destinations  name stringRequired Destination name and identity.  destination_url stringRequired on create Private URL, fingerprinted in diffs and never displayed. A change recreates the destination.  secret_token string Write-only secret token.  state string Can be one of: present, absent. Default: present	Example: gitlab_settings_instance: audit_event_destinations: - name: primary-siem destination_url: https://siem.example.com/gitlab ...
applications array of objects  Instance OAuth applications ([Applications API](https://docs.gitlab.com/api/applications/)). Applications are immutable through this API; converging redirect-URI drift recreates the application and rotates its secret. Properties of applications  name stringRequired Application name and identity.  redirect_uri stringRequired on create OAuth redirect URI. Drift recreates the application.  scopes stringRequired on create Space-separated OAuth scopes. Create-only; the list endpoint omits this value, so later scope drift is not detected.  confidential boolean Whether the OAuth application is confidential.  secret_file string (absolute path) Controller path that receives the one-time application secret at creation; written 0600 and never logged.  state string Can be one of: present, absent. Default: present	Example: gitlab_settings_instance: applications: - name: grafana-oauth redirect_uri: https://grafana.example.com/login/gitlab scopes: read_user ...
member_roles array of objects  Instance-level custom member roles ([Member roles API](https://docs.gitlab.com/api/member_roles/)). This is the self-managed home of custom roles; the group form in Labels, badges, and roles applies to GitLab.com. Roles have no update verb, so remove and recreate one to change it. Properties of member_roles  name stringRequired Custom-role name and identity.  description string Description shown for the custom role.  base_access_level integerRequired Base GitLab access level. Can be one of: 10, 15, 20, 25, 30, 40, 50.  apply_security_scan_profiles boolean Apply security scan profiles.  admin_merge_request boolean Allows approval of merge requests.  archive_project boolean Allows archiving of projects.  admin_ai_catalog_item_consumer boolean Enable, disable, and configure custom agents and flows from the AI catalog for a project.  destroy_package boolean Delete packages and package files in the package registry.  remove_project boolean Allows deletion of projects.  remove_group boolean Ability to delete or restore a subgroup. This ability does not allow deleting top-level groups. Review the retention period settings to prevent accidental deletion.  manage_security_policy_link boolean Allows linking security policy projects.  admin_ai_catalog_item boolean Create, edit, and delete custom agents and flows in the AI catalog.  admin_compliance_framework boolean Create, read, update, and delete compliance frameworks. Users with this permission can also assign a compliance framework label to a project, and set the default framework of a group.  admin_cicd_variables boolean Create, read, update, and delete CI/CD variables.  manage_deploy_tokens boolean Manage deploy tokens at the group or project level.  manage_group_access_tokens boolean Create, read, update, and delete group access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role.  admin_group_member boolean Add or remove users in a group, and assign roles to users. When assigning a role, users with this custom permission must select a role that has the same or fewer permissions as the default role used as the base for their custom role.  admin_integrations boolean Create, read, update, and delete integrations with external applications.  manage_merge_request_settings boolean Configure merge request settings at the group or project level. Group actions include managing merge checks and approval settings. Project actions include managing MR configurations, approval rules and settings, and branch targets. In order to enable Suggested reviewers, the "Manage project access tokens" custom permission needs to be enabled.  manage_project_access_tokens boolean Create, read, update, and delete project access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role.  admin_protected_branch boolean Create, read, update, and delete protected branches for a project.  admin_protected_environments boolean Create, read, update, and delete protected environments  admin_push_rules boolean Configure push rules for repositories at the group or project level.  admin_runners boolean Create, view, edit, and delete group or project Runners. Includes configuring Runner settings.  admin_security_attributes boolean Manage the security categories and attributes belonging to a top-level group. Also requires the read_security_attribute permission.  admin_terraform_state boolean Execute terraform commands, lock/unlock terraform state files, and remove file versions.  admin_vulnerability boolean Edit the status, linked issue, and severity of a vulnerability object. Also requires the read_vulnerability permission.  admin_web_hook boolean Manage webhooks  read_agent_artifacts boolean Read GitLab Duo Agent Platform artifacts, including audit events and session metadata, that are exposed through the agent artifacts dashboard.  read_compliance_dashboard boolean Read compliance capabilities including adherence, violations, and frameworks for groups and projects.  read_security_scan_profiles boolean Read security scan profiles.  read_virtual_registry boolean Allows read access to virtual registries at the group level. Enables users to resolve packages through the virtual registry without requiring broader group membership permissions. Only works on top level groups.  update_sec_ai_workflow_settings boolean Update security AI workflow settings such as SAST Vulnerability Resolution. Also requires the read_vulnerability permission.  read_admin_cicd boolean Read CI/CD details for runners and jobs in the Admin Area.  read_crm_contact boolean Read CRM contact.  read_dependency boolean Allows read-only access to the dependencies and licenses.  read_admin_groups boolean Read group details in the Admin Area.  read_admin_projects boolean Read project details in the Admin Area.  read_code boolean Allows read-only access to the source code in the user interface. Does not allow users to edit or download repository archives, clone or pull repositories, view source code in an IDE, or view merge requests for private projects. You can download individual files because read-only access inherently grants the ability to make a local copy of the file.  read_runners boolean Allows read-only access to group or project runners, including the runner fleet dashboard.  read_security_attribute boolean Allows read-only access to the security categories and attributes that belong to a top-level group.  read_admin_subscription boolean Read subscription details in the Admin area.  read_admin_monitoring boolean Read system information such as background migrations, health checks, and Gitaly in the Admin Area.  read_admin_users boolean Read the user list and user details in the Admin area.  read_vulnerability boolean Read vulnerability reports and security dashboards.  state string Can be one of: present, absent. Default: present. Drift on a present role reports through strict/compatible handling.	Example: gitlab_settings_instance: member_roles: - name: security-auditor base_access_level: 20 read_vulnerability: true ...
compliance_policy_settings object  Instance compliance and security policy settings. This singleton always exists and is neither creatable nor deletable. Properties of compliance_policy_settings  csp_namespace_id integerRequired Namespace used for centralized security policy management. Scope note: group-level compliance frameworks and security policies use GitLab's GraphQL API rather than REST. This section documents only the REST instance singleton.	Example: gitlab_settings_instance: compliance_policy_settings: csp_namespace_id: 42 ...