Project deployment surfaces: environments, protected environments (project
and group scope), deploy keys, pipeline schedules with their variables, and
registry/package protection rules.
|
environments array of objects
Project environments matched by name. GitLab only deletes stopped environments; removing a running environment surfaces GitLab's error verbatim.
Properties of environments
name stringRequired
Environment name and identity.
external_url string
Environment URL; treated as a private value and reconciled by fingerprint.
tier string
Deployment tier.
description string
Environment description.
cluster_agent_id integer
GitLab agent id associated with the environment.
kubernetes_namespace string
Kubernetes namespace associated with the environment.
flux_resource_path string
Flux resource path associated with the environment.
auto_stop_setting string
GitLab auto-stop behavior.
slug string
Environment slug accepted by the GitLab API.
state string
Can be one of: present, absent. Default: present
|
Example:
environments:
- name: production
external_url: https://service.example.com
...
|
|
protected_environments array of objects
Protected environments available on project and group entries, matched by name. Access arrays apply on create but are excluded from drift detection because they do not round-trip in request shape.
Properties of protected_environments
name stringRequired
Environment name and identity.
deploy_access_levels array of objectsRequired on create
Deployment access entries. Applied on create and excluded from drift detection.
Properties of each deploy_access_levels entry
user_id integerOne access target required
ID of a user with access to the project. Declare one of user_id, group_id, or access_level.
group_id integerOne access target required
ID of a group with access to the project. Declare one of user_id, group_id, or access_level.
group_inheritance_type integer
Membership behavior for a group_id: 0 for direct members or 1 for inherited members. Default: 0.
access_level integerOne access target required
Role allowed to deploy. Can be one of: 20, 30, 40, 60.
approval_rules array of objects
Deployment approval rules. Applied on create and excluded from drift detection.
Properties of each approval_rules entry
user_id integerOne approval target required
ID of a user allowed to approve. Declare one of user_id, group_id, or access_level.
group_id integerOne approval target required
ID of a group allowed to approve. Declare one of user_id, group_id, or access_level.
group_inheritance_type integer
Membership behavior for a group_id: 0 for direct members or 1 for inherited members. Default: 0.
access_level integerOne approval target required
Role allowed to approve. Can be one of: 20, 30, 40, 60.
required_approvals integer
Number of approvals required from this rule. Default: 1.
state string
Can be one of: present, absent. Default: present
|
Example:
protected_environments:
- name: production
deploy_access_levels:
- access_level: 40
...
|
|
deploy_keys array of objects
Project deploy keys. This API surface does not mint keys; provide the public keys to configure.
Properties of deploy_keys
title stringRequired on create
Natural identity when unique and required to create a key.
id integer
Server-assigned lookup identity for an existing key when duplicate titles exist. Lookup-only.
key stringRequired on create
Public key material. Readable but create-only; drift requires explicit recreation.
expires_at string (date-time)
Optional expiry. Readable but create-only; drift requires explicit recreation.
can_push boolean
Whether the key can push; reconciles in place.
state string
Can be one of: present, absent. Default: present
|
Example:
deploy_keys:
- title: deployer
key: "ssh-ed25519 AAAA..."
can_push: false
...
|
|
pipeline_schedules array of objects
Project pipeline schedules. On a repository with no commits yet, GitLab rejects a short ref as ambiguous; use the fully qualified form such as refs/heads/main.
Properties of pipeline_schedules
description stringRequired on create
Natural identity when unique and required to create a schedule.
id integer
Server-assigned lookup identity for an existing schedule when duplicate descriptions exist. Lookup-only.
ref stringRequired on create
Branch or tag ref; reconciles with drift detection.
cron stringRequired on create
Cron expression; reconciles with drift detection.
cron_timezone string
Cron timezone; reconciles with drift detection.
active boolean
Whether the schedule is active; reconciles with drift detection.
inputs array of objects
Values supplied to declared CI/CD inputs when the schedule runs.
Properties of each inputs entry
name stringRequired
Input name declared by the pipeline configuration.
value string, array, number, or booleanRequired
Value passed to that input.
variables object
Schedule variables keyed by variable name. A scalar value is shorthand for a present variable with variable_type: env_var.
Properties of each structured variables value
value stringRequired when state is present
Required when this variable entry's state is present (the default). Omit it when state: absent; deletion uses the variable's map key. This secret is never displayed or diffed.
variable_type string
Can be one of: env_var, file. Default: env_var.
force_secret_update boolean
Rewrite the secret value when no readable attribute drifted. Default: false.
state string
Can be one of: present, absent. Default: present.
state string
Can be one of: present, absent. Default: present
|
Example:
pipeline_schedules:
- description: nightly build
ref: main
cron: "0 2 * * *"
variables:
ENVIRONMENT: production
OLD_VAR:
state: absent
...
|
|
freeze_periods array of objects
Project deploy-freeze windows, matched by their cron-expression pair or an explicit server id.
Properties of freeze_periods
freeze_start stringRequired on create
Start cron expression. Together with freeze_end, forms the natural identity and is required to create a window.
freeze_end stringRequired on create
End cron expression. Together with freeze_start, forms the natural identity and is required to create a window.
id integer
Server-assigned lookup identity when duplicate windows exist. Lookup-only.
cron_timezone string
Cron timezone; reconciles with drift detection.
state string
Can be one of: present, absent. Default: present
|
Example:
freeze_periods:
- freeze_start: "0 23 * * 5"
freeze_end: "0 7 * * 1"
cron_timezone: UTC
...
|
|
registry_protection_rules array of objects
Container repository protection rules. GitLab validates repository patterns server-side; a pattern must begin with the project's full path.
Properties of registry_protection_rules
repository_path_pattern stringRequired
Repository path pattern and identity.
minimum_access_level_for_push string or integer
Minimum push access; reconciles via PATCH.
minimum_access_level_for_delete string or integer
Minimum delete access; reconciles via PATCH.
state string
Can be one of: present, absent. Default: present
|
Example:
registry_protection_rules:
- repository_path_pattern: "platform/service/prod*"
minimum_access_level_for_push: maintainer
...
|
|
package_protection_rules array of objects
Project package protection rules. GitLab validates patterns server-side; an npm pattern must be a valid package name, such as @group/prefix-*.
Properties of package_protection_rules
package_name_pattern stringRequired
Package name pattern and identity.
package_type stringRequired on create
GitLab package type, such as npm.
minimum_access_level_for_push string or integer
Minimum push access; reconciles via PATCH.
minimum_access_level_for_delete string or integer
Minimum delete access; reconciles via PATCH.
state string
Can be one of: present, absent. Default: present
|
Example:
package_protection_rules:
- package_name_pattern: "@platform/*"
package_type: npm
minimum_access_level_for_push: maintainer
...
|
|
registry_tag_protection_rules array of objects
Container registry tag protection rules, distinct from repository rules that match image paths. Instance-gated: requires the next-generation container registry metadata API.
Properties of registry_tag_protection_rules
tag_name_pattern stringRequired
Tag pattern and identity.
minimum_access_level_for_push string or integerRequired on create
Minimum push access; reconciles via PATCH.
minimum_access_level_for_delete string or integerRequired on create
Minimum delete access; reconciles via PATCH.
state string
Can be one of: present, absent. Default: present
A deployment without the metadata API refuses these rules with "GitLab container registry API not supported" because the instance does not expose the required API.
|
Example:
registry_tag_protection_rules:
- tag_name_pattern: "v*"
minimum_access_level_for_push: maintainer
minimum_access_level_for_delete: maintainer
...
|