Skip to content

admin.md

Latest commit

 

History

History
784 lines (489 loc) · 24.2 KB

admin.md

File metadata and controls

784 lines (489 loc) · 24.2 KB
Raw

Administration — Tool Reference

Diátaxis type: Reference Domain: Administration Individual tools: 75 Meta-tool: gitlab_admin (GITLAB_MCP_TOOL_SURFACE=meta catalog) — one tool for the whole domain, Terraform states, cluster agents and the dependency proxy included Dynamic IDs: admin.*, audit_event.* (default surface, via gitlab_execute_action) GitLab API: Settings · Appearance · Broadcast Messages · Features · License · System Hooks · Sidekiq · Plan Limits · Usage Data · Audit Events · Terraform States · Cluster Agents Audience: 👤 End users, AI assistant users

Overview

The administration domain covers instance-level settings, appearance, broadcast messages, admin feature flags, licensing, system hooks, Sidekiq metrics, plan limits, usage data, database migrations, OAuth2 applications, application statistics, instance metadata, custom attributes, bulk imports, dependency proxy, audit events, Terraform states, and cluster agents.

On the default dynamic surface, these operations are the admin.*, audit_event.* entries of the canonical action catalog: find them with gitlab_find_action and run them with gitlab_execute_action by domain.action ID. With GITLAB_MCP_TOOL_SURFACE=individual, each is the tool named in the tables below.

With GITLAB_MCP_TOOL_SURFACE=meta, every sub-package on this page is consolidated into a single gitlab_admin meta-tool that dispatches by action parameter. Terraform states, cluster agents and the dependency proxy have no meta-tool of their own — they are actions on gitlab_admin, such as terraform_state_list, cluster_agent_get and dependency_proxy_delete.

Common Questions

"Show the GitLab server settings" "List active broadcast messages" "Check the server version"

Annotation Legend

Annotation ReadOnly Destructive Idempotent Description
Read Yes No Yes Safe read-only operation
Create — No — Creates a new resource
Update — No Yes Modifies an existing resource
Delete — Yes Yes Destroys a resource; protected by confirmation

Tools marked Delete require user confirmation before execution.

Application Settings

gitlab_get_settings

Get current application settings. Requires admin access. Returns all instance-level settings as key-value pairs.

Annotation Read

gitlab_update_settings

Update application settings. Requires admin access. Pass settings as key-value map with snake_case keys matching GitLab API (e.g. signup_enabled, default_project_visibility).

Annotation Update

Appearance

gitlab_get_appearance

Get current application appearance settings. Requires admin access.

Annotation Read

gitlab_update_appearance

Update application appearance (title, description, messages, PWA settings). Requires admin access.

Annotation Update

Broadcast Messages

gitlab_list_broadcast_messages

List all broadcast messages. Requires admin access.

Annotation Read

gitlab_get_broadcast_message

Get a specific broadcast message by ID. Requires admin access.

Annotation Read

gitlab_create_broadcast_message

Create a broadcast message. Requires admin access.

Annotation Create

gitlab_update_broadcast_message

Update a broadcast message. Requires admin access.

Annotation Update

gitlab_delete_broadcast_message

Delete a broadcast message. Requires admin access.

Annotation Delete

Destructive: Protected by confirmation prompt.

Admin Feature Flags

gitlab_list_features

List all feature flags (admin). Returns name, state and gates for each flag.

Annotation Read

gitlab_list_feature_definitions

List all feature definitions (admin). Returns name, type, group, milestone and default_enabled for each definition.

Annotation Read

gitlab_set_feature_flag

Set or create a feature flag (admin). Requires name and value. Supports scoping to user, group, project, namespace, or repository.

Annotation Create

gitlab_delete_feature_flag

Delete a feature flag (admin). Requires the flag name.

Annotation Delete

Destructive: Protected by confirmation prompt.

License

gitlab_get_license

Get current GitLab license information (admin). Returns plan, expiry, user counts and licensee.

Annotation Read

gitlab_add_license

Add a new GitLab license (admin). Requires the Base64-encoded license string.

Annotation Create

gitlab_delete_license

Delete a GitLab license by ID (admin).

Annotation Delete

Destructive: Protected by confirmation prompt.

System Hooks

gitlab_list_system_hooks

List all system hooks (admin). Returns ID, URL and event subscriptions.

Annotation Read

gitlab_get_system_hook

Get a system hook by ID (admin).

Annotation Read

gitlab_add_system_hook

Add a new system hook (admin). Requires URL. Optionally configure event subscriptions, SSL verification, payload token, and write-only signing token.

Annotation Create

gitlab_edit_system_hook

Edit an existing system hook by ID (admin). Supports URL, metadata, event subscriptions, SSL verification, payload token, and write-only signing token updates.

Annotation Update

gitlab_test_system_hook

Test a system hook by ID (admin). Triggers a test event and returns the result. Nothing changes on the instance, but GitLab delivers an event to the hook's configured URL, so the action is classified as mutating on every surface: --read-only removes it and --safe-mode previews it.

Annotation Create

gitlab_set_system_hook_url_variable

Create or update a URL variable for a system hook (admin). Variables can be referenced as placeholders in the hook URL.

Annotation Update

gitlab_delete_system_hook_url_variable

Delete a URL variable from a system hook (admin).

Annotation Delete

Destructive: Protected by confirmation prompt.

gitlab_delete_system_hook

Delete a system hook by ID (admin).

Annotation Delete

Destructive: Protected by confirmation prompt.

Sidekiq Metrics

gitlab_get_sidekiq_queue_metrics

Get Sidekiq queue metrics (admin). Returns backlog and latency for all queues.

Annotation Read

gitlab_get_sidekiq_process_metrics

Get Sidekiq process metrics (admin). Returns information about running Sidekiq processes.

Annotation Read

gitlab_get_sidekiq_job_stats

Get Sidekiq job statistics (admin). Returns processed, failed, and enqueued counts.

Annotation Read

gitlab_get_sidekiq_compound_metrics

Get all Sidekiq metrics in a single compound response (admin). Returns queue metrics, process metrics, and job statistics combined.

Annotation Read

Plan Limits

gitlab_get_plan_limits

Get current plan limits (admin). Optionally filter by plan name (default, free, bronze, silver, gold, premium, ultimate).

Annotation Read

gitlab_change_plan_limits

Change plan limits (admin). Requires plan_name; optionally set individual file size limits.

Annotation Update

Usage Data

gitlab_get_service_ping

Get service ping data (admin). Returns recorded_at, license info, and usage counts.

Annotation Read

gitlab_get_non_sql_metrics

Get non-SQL service ping metrics (admin). Returns instance info, license details, and settings.

Annotation Read

gitlab_get_usage_queries

Get service ping SQL queries (admin). Returns the raw SQL queries used for service ping collection.

Annotation Read

gitlab_get_metric_definitions

Get metric definitions as YAML (admin). Returns all metric definitions used in service ping.

Annotation Read

gitlab_track_event

Track a single usage event. Params: event (required), send_to_snowplow, namespace_id, project_id.

Annotation Create

gitlab_track_events

Track multiple usage events in batch. Params: events (required, array of event objects).

Annotation Create

Database Migrations

gitlab_mark_migration

Mark a pending database migration as successfully executed (admin). Params: version (required), database (optional).

Annotation Update

OAuth2 Applications

gitlab_list_applications

List all OAuth2 applications (admin). Params: page, per_page.

Annotation Read

gitlab_create_application

Create an OAuth2 application (admin). Params: name (required), redirect_uri (required), scopes (required), confidential.

Annotation Create

gitlab_renew_application_secret

Renew (rotate) an OAuth2 application secret (admin). Params: id (required). The previous secret is invalidated immediately and the response carries the new secret, which cannot be retrieved later.

Annotation Create

gitlab_delete_application

Delete an OAuth2 application (admin). Params: id (required).

Annotation Delete

Destructive: Protected by confirmation prompt.

Application Statistics

gitlab_get_application_statistics

Get application statistics (admin). Returns counts for users, projects, groups, issues, MRs, etc.

Annotation Read

Instance Metadata

gitlab_get_metadata

Get GitLab instance metadata (version, revision, KAS info, enterprise flag).

Annotation Read

Custom Attributes

gitlab_list_custom_attributes

List custom attributes for a user, group, or project (admin). Params: resource_type (required: user|group|project), resource_id (required).

Annotation Read

gitlab_get_custom_attribute

Get a custom attribute by key for a user, group, or project (admin). Params: resource_type (required), resource_id (required), key (required).

Annotation Read

gitlab_set_custom_attribute

Set (create/update) a custom attribute for a user, group, or project (admin). Params: resource_type (required), resource_id (required), key (required), value (required).

Annotation Create

gitlab_delete_custom_attribute

Delete a custom attribute for a user, group, or project (admin). Params: resource_type (required), resource_id (required), key (required).

Annotation Delete

Destructive: Protected by confirmation prompt.

Bulk Imports

gitlab_start_bulk_import

Start a new group or project bulk import migration (admin). Requires source GitLab URL, access token, and entities to migrate.

Annotation Create

gitlab_list_bulk_imports

List all group or project bulk import migrations visible to the caller. Optionally filter by status.

Annotation Read

gitlab_get_bulk_import

Get details of a single bulk import migration by ID.

Annotation Read

gitlab_cancel_bulk_import

Cancel an in-progress bulk import migration. Returns the migration with updated status.

Annotation Update

gitlab_list_bulk_import_entities

List bulk import migration entities. When bulk_import_id is provided, scopes to that import; otherwise returns all entities visible to the caller. Optionally filter by status.

Annotation Read

gitlab_get_bulk_import_entity

Get details of a single bulk import migration entity by bulk_import_id and entity_id.

Annotation Read

gitlab_list_bulk_import_entity_failures

List failed import records for a bulk import migration entity. Useful for diagnosing failed migrations.

Annotation Read

Dependency Proxy

gitlab_purge_dependency_proxy

Purge the dependency proxy cache for a GitLab group.

Annotation Delete

Destructive: Protected by confirmation prompt.

Terraform States

gitlab_list_terraform_states

List Terraform states for a GitLab project.

Annotation Read

gitlab_get_terraform_state

Get details of a Terraform state.

Annotation Read

gitlab_delete_terraform_state

Delete a Terraform state.

Annotation Delete

Destructive: Protected by confirmation prompt.

gitlab_delete_terraform_state_version

Delete a specific version of a Terraform state.

Annotation Delete

Destructive: Protected by confirmation prompt.

gitlab_lock_terraform_state

Lock a Terraform state.

Annotation Update

gitlab_unlock_terraform_state

Unlock a Terraform state.

Annotation Update

Cluster Agents

gitlab_list_cluster_agents

List cluster agents for a GitLab project.

Annotation Read

gitlab_get_cluster_agent

Get details of a cluster agent.

Annotation Read

gitlab_register_cluster_agent

Register a new cluster agent for a GitLab project.

Annotation Create

gitlab_delete_cluster_agent

Delete a cluster agent.

Annotation Delete

Destructive: Protected by confirmation prompt.

gitlab_list_cluster_agent_tokens

List tokens for a cluster agent.

Annotation Read

gitlab_get_cluster_agent_token

Get details of a cluster agent token.

Annotation Read

gitlab_create_cluster_agent_token

Create a token for a cluster agent.

Annotation Create

gitlab_revoke_cluster_agent_token

Revoke a cluster agent token.

Annotation Delete

Destructive: Protected by confirmation prompt.

Audit Events

gitlab_list_instance_audit_events

List instance-level audit events (admin only). Supports filtering by date range.

Annotation Read

gitlab_get_instance_audit_event

Get a single instance-level audit event by ID (admin only).

Annotation Read

gitlab_list_group_audit_events

List audit events for a GitLab group. Supports filtering by date range.

Annotation Read

gitlab_get_group_audit_event

Get a single group-level audit event by ID.

Annotation Read

gitlab_list_project_audit_events

List audit events for a GitLab project. Supports filtering by date range.

Annotation Read

gitlab_get_project_audit_event

Get a single project-level audit event by ID.

Annotation Read

Tool Summary

# Tool Name Category Annotation
1 gitlab_get_settings Settings Read
2 gitlab_update_settings Settings Update
3 gitlab_get_appearance Appearance Read
4 gitlab_update_appearance Appearance Update
5 gitlab_list_broadcast_messages Broadcast Messages Read
6 gitlab_get_broadcast_message Broadcast Messages Read
7 gitlab_create_broadcast_message Broadcast Messages Create
8 gitlab_update_broadcast_message Broadcast Messages Update
9 gitlab_delete_broadcast_message Broadcast Messages Delete
10 gitlab_list_features Admin Features Read
11 gitlab_list_feature_definitions Admin Features Read
12 gitlab_set_feature_flag Admin Features Create
13 gitlab_delete_feature_flag Admin Features Delete
14 gitlab_get_license License Read
15 gitlab_add_license License Create
16 gitlab_delete_license License Delete
17 gitlab_list_system_hooks System Hooks Read
18 gitlab_get_system_hook System Hooks Read
19 gitlab_add_system_hook System Hooks Create
20 gitlab_edit_system_hook System Hooks Update
21 gitlab_test_system_hook System Hooks Create
22 gitlab_set_system_hook_url_variable System Hooks Update
23 gitlab_delete_system_hook_url_variable System Hooks Delete
24 gitlab_delete_system_hook System Hooks Delete
25 gitlab_get_sidekiq_queue_metrics Sidekiq Read
26 gitlab_get_sidekiq_process_metrics Sidekiq Read
27 gitlab_get_sidekiq_job_stats Sidekiq Read
28 gitlab_get_sidekiq_compound_metrics Sidekiq Read
29 gitlab_get_plan_limits Plan Limits Read
30 gitlab_change_plan_limits Plan Limits Update
31 gitlab_get_service_ping Usage Data Read
32 gitlab_get_non_sql_metrics Usage Data Read
33 gitlab_get_usage_queries Usage Data Read
34 gitlab_get_metric_definitions Usage Data Read
35 gitlab_track_event Usage Data Create
36 gitlab_track_events Usage Data Create
37 gitlab_mark_migration DB Migrations Update
38 gitlab_list_applications Applications Read
39 gitlab_create_application Applications Create
40 gitlab_delete_application Applications Delete
41 gitlab_renew_application_secret Applications Create
42 gitlab_get_application_statistics Statistics Read
43 gitlab_get_metadata Metadata Read
44 gitlab_list_custom_attributes Custom Attributes Read
45 gitlab_get_custom_attribute Custom Attributes Read
46 gitlab_set_custom_attribute Custom Attributes Create
47 gitlab_delete_custom_attribute Custom Attributes Delete
48 gitlab_start_bulk_import Bulk Imports Create
49 gitlab_list_bulk_imports Bulk Imports Read
50 gitlab_get_bulk_import Bulk Imports Read
51 gitlab_cancel_bulk_import Bulk Imports Update
52 gitlab_list_bulk_import_entities Bulk Imports Read
53 gitlab_get_bulk_import_entity Bulk Imports Read
54 gitlab_list_bulk_import_entity_failures Bulk Imports Read
55 gitlab_purge_dependency_proxy Dependency Proxy Delete
56 gitlab_list_terraform_states Terraform States Read
57 gitlab_get_terraform_state Terraform States Read
58 gitlab_delete_terraform_state Terraform States Delete
59 gitlab_delete_terraform_state_version Terraform States Delete
60 gitlab_lock_terraform_state Terraform States Update
61 gitlab_unlock_terraform_state Terraform States Update
62 gitlab_list_cluster_agents Cluster Agents Read
63 gitlab_get_cluster_agent Cluster Agents Read
64 gitlab_register_cluster_agent Cluster Agents Create
65 gitlab_delete_cluster_agent Cluster Agents Delete
66 gitlab_list_cluster_agent_tokens Cluster Agents Read
67 gitlab_get_cluster_agent_token Cluster Agents Read
68 gitlab_create_cluster_agent_token Cluster Agents Create
69 gitlab_revoke_cluster_agent_token Cluster Agents Delete
70 gitlab_list_instance_audit_events Audit Events Read
71 gitlab_get_instance_audit_event Audit Events Read
72 gitlab_list_group_audit_events Audit Events Read
73 gitlab_get_group_audit_event Audit Events Read
74 gitlab_list_project_audit_events Audit Events Read
75 gitlab_get_project_audit_event Audit Events Read

Destructive Tools (Require Confirmation)

The following tools are annotated with DestructiveHint: true and require user confirmation before execution:

  • gitlab_delete_broadcast_message — deletes a broadcast message
  • gitlab_delete_feature_flag — deletes an admin feature flag
  • gitlab_delete_license — deletes a GitLab license
  • gitlab_delete_system_hook_url_variable — deletes a system hook URL variable
  • gitlab_delete_system_hook — deletes a system hook
  • gitlab_delete_application — deletes an OAuth2 application
  • gitlab_delete_custom_attribute — deletes a custom attribute
  • gitlab_purge_dependency_proxy — purges the dependency proxy cache
  • gitlab_delete_terraform_state — deletes a Terraform state
  • gitlab_delete_terraform_state_version — deletes a Terraform state version
  • gitlab_delete_cluster_agent — deletes a cluster agent
  • gitlab_revoke_cluster_agent_token — revokes a cluster agent token

Related