terraform-gitlab-project

Supported Configuration Paths

• Choose exactly one namespace-selection path per project:
  • set namespace_id directly, or
  • set group_key to a declared gitlab_groups entry, or
  • omit both only when exactly one gitlab_groups entry exists and you want the implicit single-group fallback
• Do not set namespace_id and group_key together on the same project.
• Declare each gitlab_groups entry in one of two modes:
  • managed group: create = true with name and path
  • existing group reference: create = false with existing_group_id
• Project env_variables override global_env_variables by key, and the project-level entry replaces the full shared definition for that key.
• projects_enabled = false skips projects and project-scoped child resources, but still allows managed groups to be created.
• Field-level defaults, allowed values, and behavior notes now live inline next to the owning attributes in variables.tf instead of a separate shared project-field description block.
• Existing consumers can keep using the documented single-group fallback; this clarification pass does not expand the module into runners, Kubernetes, or other unrelated GitLab platform areas.

Requirements

Name	Version
terraform	>= 1.3
gitlab	>= 18.8.2

Providers

No providers.

Modules

Name	Source	Version
ci_env_variables	./modules/ci_env_variables	n/a
gitlab_group	./modules/gitlab_group	n/a
project	./modules/project	n/a

Resources

No resources.

Inputs

Name	Description	Type	Default	Required
gitlab_groups	GitLab groups for this module (each entry needs a unique "key"). Each entry must be one of two supported modes: - managed group: set create = true and provide name + path - existing group reference: set create = false and provide existing_group_id Projects may resolve their namespace through group_key, or by the implicit single-group fallback when exactly one gitlab_groups entry exists. If this list is empty, every gitlab_projects item must set namespace_id directly.	list(object({ key = string # Stable id for wiring group_key on projects create = optional(bool, false) # Create group via API for this entry name = optional(string) # Display name (required if create is true) path = optional(string) # URL path (required if create is true) description = optional(string, "") # Group description visibility_level = optional(string, "private") # private	internal	public parent_id = optional(number) # Parent namespace id for subgroups existing_group_id = optional(number) # Existing GitLab group id (namespace id) when create is false; ignored when create is true }))
gitlab_projects	List of GitLab project configurations. Supported namespace selection paths: - set namespace_id directly - set group_key to select an entry from var.gitlab_groups - omit both namespace_id and group_key only when exactly one gitlab_groups entry exists; that single group is used implicitly Do not set namespace_id and group_key together on the same project. When gitlab_groups is empty, set namespace_id on every project. Merge behavior (per project; GitLab UI under Settings → Merge requests): squash_option — Squash commits when merging: - never → Do not allow (squash disabled; checkbox hidden) - default_off → Allow (checkbox visible, off by default) - default_on → Encourage (checkbox visible, on by default) - always → Require (always squash; user cannot disable) merge_method — Merge method: - merge → Create a merge commit - rebase_merge → Merge commit with semi-linear history - ff → Fast-forward merge branch_protections — Optional list per project: Settings → Repository → Protected branches. When omitted or set to [], this module creates one default protection for branch "main". Access is only via merge_access_level / push_access_level (maintainer, developer, admin, no one). Granular "specific users/groups" rows from the GitLab UI are not supported by provider resource gitlab_branch_protection. approval_rule — Optional per project. Accepts a list of approval rule objects. When omitted or set to [], no project approval rule resources are created. Defaults are name = "Approval rule", approvals_required = 1, applies_to_all_protected_branches = false (user_ids / group_ids optional; omit approver lists to use GitLab default approvers for the rule). prevent_destroy — Contract hint for operators and downstream tooling only; this module does not set Terraform lifecycle { prevent_destroy } from this field (dynamic lifecycle is not supported for count/for_each resources in the same way as static blocks). ci_pipeline_variables_minimum_override_role — CI/CD → Variables: minimum role that may run a new pipeline with pipeline variables (GitLab 17.1+). Valid values: no_one_allowed, developer, maintainer, owner. Default in type: maintainer. approval_rule — Optional per project. Accepts a list of approval rule objects. If present and non-empty, the module creates one GitLab approval rule resource per list entry. Defaults are name = "Approval rule", approvals_required = 1, applies_to_all_protected_branches = false (user_ids / group_ids optional; omit approver lists to use GitLab default approvers for the rule). env_variables — Per-project CI/CD variables (gitlab_project_variable via module ci_env_variables), merged with var.global_env_variables; the same key on the project replaces the full global variable definition for that project.	list(object({ name = string # Project name / slug key used by child resources description = optional(string) # Project description visibility_level = optional(string, "private") # private	internal	public default_branch = optional(string, "develop") # Initial default branch name initialize_with_readme = optional(bool, true) # Create repository with README request_access_enabled = optional(bool, true) # Allow users to request access prevent_destroy = optional(bool, true) # Contract hint only; not mapped to Terraform lifecycle namespace_id = optional(number) # Explicit GitLab namespace id for the project group_key = optional(string) # Resolve namespace through gitlab_groups[].key lfs_enabled = optional(bool, true) # Enable Git LFS for the project packages_enabled = optional(bool, true) # Enable GitLab package registry squash_option = optional(string, "default_on") # never
global_env_variables	Environment variables applied to every GitLab project. Use for shared NPM_TOKEN, GITLAB_TOKEN, etc.	list(object({ key = string # CI/CD variable name value = string # Variable value (use masked for secrets) masked = optional(bool, false) # Hide value in job logs / UI where supported protected = optional(bool, false) # Available only on protected branches/tags }))	[]	no
projects_enabled	When false, skips creating GitLab projects and project-scoped child resources (for example CI variables). GitLab groups are still created when gitlab_groups[].create is true.	bool	true	no

Outputs

Name	Description
gitlab_group_full_paths	Map of group key to full_path for groups created by this module (Terraform-managed only; existing groups referenced via existing_group_id are not listed here).
gitlab_group_ids	Map of group key (from gitlab_groups) to namespace id for every resolvable configured group — managed groups contribute their created id and existing-group references require existing_group_id.
gitlab_project_ids	Map of GitLab project name to project ID