Environment

Use {"action":"create","params":{...}}; only top-level keys are action and params. Action params schema: gitlab://schema/meta/gitlab_environment/.

Manage GitLab deployment environments, protected environments, freeze (deploy block) periods, and the deployment record audit trail. Delete and stop are destructive (stop terminates the running env; force=true skips on-stop jobs). When to use: define/update environments (production, staging, review/*), restrict who can deploy via protected environments, schedule deploy freezes, audit deployment history, approve/reject deployments awaiting manual gate. NOT for: CI/CD variables scoped to environments (use gitlab_ci_variable), pipelines/jobs (use gitlab_pipeline / gitlab_job), feature flag rollout strategies (use gitlab_feature_flags).

Behavior:

• Idempotent reads: list / get / protected_list / protected_get / freeze_list / freeze_get / deployment_list / deployment_get / deployment_merge_requests.

• update / protected_update / freeze_update / deployment_update are idempotent (same input → same state). create / protected_protect / freeze_create / deployment_create are NON-idempotent on duplicate (project_id, name) — return 409. deployment_approve_or_reject is single-shot per (deployment_id, user) and cannot be reversed.

• Side effects: stop runs the on-stop CI job (unless force=true) and terminates any review-app resources; deployment_approve_or_reject may release queued CI jobs awaiting a manual gate; freeze_create immediately blocks deploys that match the cron window.

• Destructive: delete and stop are destructive — stop cannot be reversed without re-deploying; deployment_delete removes the deployment audit record (history loss).

Returns: resource object (environment / protection / freeze / deployment) for _get/_create/_update/_protect; paginated array for *_list; updated deployment with approval state for deployment_approve_or_reject; MR list for deployment_merge_requests; {success, message} for _delete/_unprotect/stop. Errors: 404 not found, 403 forbidden (hint: protect/unprotect require Maintainer+), 400 invalid params (hint: tier ∈ production/staging/testing/development/other; freeze cron timezone must be valid TZ name).

Param conventions: * = required. All actions need project_id*. environment_id is the numeric ID returned by list/create.

Environments:

• list: project_id*, name, search, states (available/stopped/stopping), page, per_page

• get / delete: project_id*, environment_id*

• create: project_id*, name*, description, external_url, tier (production/staging/testing/development/other)

• update: project_id*, environment_id*, name, description, external_url, tier

• stop: project_id*, environment_id*, force (bool) — force skips on-stop jobs

Protected environments:

• protected_list: project_id*, page, per_page

• protected_get / protected_unprotect: project_id*, environment* (environment name; name is accepted as an alias)

• protected_protect: project_id*, name*, deploy_access_levels, approval_rules

• protected_update: project_id*, environment*, name, deploy_access_levels, approval_rules

Freeze periods (cron expressions):

• freeze_list: project_id*, page, per_page

• freeze_get / freeze_delete: project_id*, freeze_period_id*

• freeze_create: project_id*, freeze_start* (cron, e.g. '0 23 * * 5'), freeze_end* (cron), cron_timezone

• freeze_update: project_id*, freeze_period_id*, freeze_start, freeze_end, cron_timezone

Deployments (immutable history records):

• deployment_list: project_id*, order_by, sort, environment, status, page, per_page

• deployment_get / deployment_delete: project_id*, deployment_id*

• deployment_create: project_id*, environment*, ref*, sha*, tag (bool), status (created/running/success/failed/canceled)

• deployment_update: project_id*, deployment_id*, status*

• deployment_approve_or_reject: project_id*, deployment_id*, status* (approved/rejected), comment

• deployment_merge_requests: project_id*, deployment_id*, state, order_by, sort, page, per_page

See also: gitlab_pipeline / gitlab_job (CI runs deploying to environments), gitlab_ci_variable (env-scoped variables), gitlab_feature_flags (env-scoped strategies).