The gitlab_project
resource allows to manage the lifecycle of a project.
A project can either be created in a group or user namespace.
Upstream API: GitLab REST API docs
resource "gitlab_project" "example" {
name = "example"
description = "My awesome codebase"
visibility_level = "public"
}
# Project with custom push rules
resource "gitlab_project" "example-two" {
name = "example-two"
push_rules {
author_email_regex = "@example\\.com$"
commit_committer_check = true
member_check = true
prevent_secrets = true
}
}
# Create a project for a given user (requires admin access)
data "gitlab_user" "peter_parker" {
username = "peter_parker"
}
resource "gitlab_project" "peters_repo" {
name = "peters-repo"
description = "This is a description"
namespace_id = data.gitlab_user.peter_parker.namespace_id
}
# Fork a project
resource "gitlab_project" "fork" {
name = "my-fork"
description = "This is a fork"
forked_from_project_id = gitlab_project.example.id
}
# Fork a project and setup a pull mirror
resource "gitlab_project" "fork" {
name = "my-fork"
description = "This is a fork"
forked_from_project_id = gitlab_project.example.id
import_url = gitlab_project.example.http_url_to_repo
mirror = true
}
# Create a project by importing it from a public project
resource "gitlab_project" "import_public" {
name = "import-from-public-project"
import_url = "https://gitlab.example.com/repo.git"
}
# Create a project by importing it from a public project and setup the pull mirror
resource "gitlab_project" "import_public_with_mirror" {
name = "import-from-public-project"
import_url = "https://gitlab.example.com/repo.git"
mirror = true
}
# Create a project by importing it from a private project
resource "gitlab_project" "import_private" {
name = "import-from-public-project"
import_url = "https://gitlab.example.com/repo.git"
import_url_username = "user"
import_url_password = "pass"
}
# Create a project by importing it from a private project and setup the pull mirror
resource "gitlab_project" "import_private_with_mirror" {
name = "import-from-public-project"
import_url = "https://gitlab.example.com/repo.git"
import_url_username = "user"
import_url_password = "pass"
mirror = true
}
# Create a project by importing it from a private project and provide credentials in `import_url`
# NOTE: only use this if you really must, use `import_url_username` and `import_url_password` whenever possible
# GitLab API will always return the `import_url` without credentials, therefore you must ignore the `import_url` for changes:
resource "gitlab_project" "import_private" {
name = "import-from-public-project"
import_url = "https://user:pass@gitlab.example.com/repo.git"
lifecycle {
ignore_changes = [
import_url
]
}
}
name
(String) The name of the project.allow_merge_on_skipped_pipeline
(Boolean) Set to true if you want to treat skipped pipelines as if they finished with success.analytics_access_level
(String) Set the analytics access level. Valid values are disabled
, private
, enabled
.approvals_before_merge
(Number) Number of merge request approvals required for merging. Default is 0.
This field does not work well in combination with the gitlab_project_approval_rule
resource
and is most likely gonna be deprecated in a future GitLab version (see this upstream epic).
In the meantime we recommend against using this attribute and use gitlab_project_approval_rule
instead.archive_on_destroy
(Boolean) Set to true
to archive the project instead of deleting on destroy. If set to true
it will entire omit the DELETE
operation.archived
(Boolean) Whether the project is in read-only mode (archived). Repositories can be archived/unarchived by toggling this parameter.auto_cancel_pending_pipelines
(String) Auto-cancel pending pipelines. This isn’t a boolean, but enabled/disabled.auto_devops_deploy_strategy
(String) Auto Deploy strategy. Valid values are continuous
, manual
, timed_incremental
.auto_devops_enabled
(Boolean) Enable Auto DevOps for this project.autoclose_referenced_issues
(Boolean) Set whether auto-closing referenced issues on default branch.avatar
(String) A local path to the avatar image to upload. Note: not available for imported resources.avatar_hash
(String) The hash of the avatar image. Use filesha256("path/to/avatar.png")
whenever possible. Note: this is used to trigger an update of the avatar. If it's not given, but an avatar is given, the avatar will be updated each time.build_coverage_regex
(String, Deprecated) Test coverage parsing for the project. This is deprecated feature in GitLab 15.0.build_git_strategy
(String) The Git strategy. Defaults to fetch. Valid values are clone
, fetch
.build_timeout
(Number) The maximum amount of time, in seconds, that a job can run.builds_access_level
(String) Set the builds access level. Valid values are disabled
, private
, enabled
.ci_config_path
(String) Custom Path to CI config file.ci_default_git_depth
(Number) Default number of revisions for shallow cloning.ci_forward_deployment_enabled
(Boolean) When a new deployment job starts, skip older deployment jobs that are still pending.ci_restrict_pipeline_cancellation_role
(String) The role required to cancel a pipeline or job. Introduced in GitLab 16.8. Premium and Ultimate only. Valid values are developer
, maintainer
, no one
ci_separated_caches
(Boolean) Use separate caches for protected branches.container_expiration_policy
(Block List, Max: 1) Set the image cleanup policy for this project. Note: this field is sometimes named container_expiration_policy_attributes
in the GitLab Upstream API. (see below for nested schema)container_registry_access_level
(String) Set visibility of container registry, for this project. Valid values are disabled
, private
, enabled
.container_registry_enabled
(Boolean, Deprecated) Enable container registry for the project.default_branch
(String) The default branch for the project.description
(String) A description of the project.emails_disabled
(Boolean, Deprecated) Disable email notifications.emails_enabled
(Boolean) Enable email notifications.environments_access_level
(String) Set the environments access level. Valid values are disabled
, private
, enabled
.external_authorization_classification_label
(String) The classification label for the project.feature_flags_access_level
(String) Set the feature flags access level. Valid values are disabled
, private
, enabled
.forked_from_project_id
(Number) The id of the project to fork. During create the project is forked and during an update the fork relation is changed.forking_access_level
(String) Set the forking access level. Valid values are disabled
, private
, enabled
.group_runners_enabled
(Boolean) Enable group runners for this project.group_with_project_templates_id
(Number) For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires use_custom_template to be true (enterprise edition).import_url
(String) Git URL to a repository to be imported. Together with mirror = true
it will setup a Pull Mirror. This can also be used together with forked_from_project_id
to setup a Pull Mirror for a fork. The fork takes precedence over the import. Make sure to provide the credentials in import_url_username
and import_url_password
. GitLab never returns the credentials, thus the provider cannot detect configuration drift in the credentials. They can also not be imported using terraform import
. See the examples section for how to properly use it.import_url_password
(String, Sensitive) The password for the import_url
. The value of this field is used to construct a valid import_url
and is only related to the provider. This field cannot be imported using terraform import
. See the examples section for how to properly use it.import_url_username
(String) The username for the import_url
. The value of this field is used to construct a valid import_url
and is only related to the provider. This field cannot be imported using terraform import
. See the examples section for how to properly use it.infrastructure_access_level
(String) Set the infrastructure access level. Valid values are disabled
, private
, enabled
.initialize_with_readme
(Boolean) Create main branch with first commit containing a README.md file.issues_access_level
(String) Set the issues access level. Valid values are disabled
, private
, enabled
.issues_enabled
(Boolean) Enable issue tracking for the project.issues_template
(String) Sets the template for new issues in the project.keep_latest_artifact
(Boolean) Disable or enable the ability to keep the latest artifact for this project.lfs_enabled
(Boolean) Enable LFS for the project.merge_commit_template
(String) Template used to create merge commit message in merge requests. (Introduced in GitLab 14.5.)merge_method
(String) Set the merge method. Valid values are merge
, rebase_merge
, ff
.merge_pipelines_enabled
(Boolean) Enable or disable merge pipelines.merge_requests_access_level
(String) Set the merge requests access level. Valid values are disabled
, private
, enabled
.merge_requests_enabled
(Boolean) Enable merge requests for the project.merge_requests_template
(String) Sets the template for new merge requests in the project.merge_trains_enabled
(Boolean) Enable or disable merge trains. Requires merge_pipelines_enabled
to be set to true
to take effect.mirror
(Boolean) Enable project pull mirror.mirror_overwrites_diverged_branches
(Boolean) Enable overwrite diverged branches for a mirrored project.mirror_trigger_builds
(Boolean) Enable trigger builds on pushes for a mirrored project.monitor_access_level
(String) Set the monitor access level. Valid values are disabled
, private
, enabled
.mr_default_target_self
(Boolean) For forked projects, target merge requests to this project. If false, the target will be the upstream project.namespace_id
(Number) The namespace (group or user) of the project. Defaults to your user.only_allow_merge_if_all_discussions_are_resolved
(Boolean) Set to true if you want allow merges only if all discussions are resolved.only_allow_merge_if_pipeline_succeeds
(Boolean) Set to true if you want allow merges only if a pipeline succeeds.only_mirror_protected_branches
(Boolean) Enable only mirror protected branches for a mirrored project.packages_enabled
(Boolean) Enable packages repository for the project.pages_access_level
(String) Enable pages access control. Valid values are public
, private
, enabled
, disabled
.path
(String) The path of the repository.pipelines_enabled
(Boolean, Deprecated) Enable pipelines for the project. The pipelines_enabled
field is being sent as jobs_enabled
in the GitLab API calls.printing_merge_request_link_enabled
(Boolean) Show link to create/view merge request when pushing from the command linepublic_builds
(Boolean, Deprecated) If true, jobs can be viewed by non-project members.public_jobs
(Boolean) If true, jobs can be viewed by non-project members.push_rules
(Block List, Max: 1) Push rules for the project. (see below for nested schema)releases_access_level
(String) Set the releases access level. Valid values are disabled
, private
, enabled
.remove_source_branch_after_merge
(Boolean) Enable Delete source branch
option by default for all new merge requests.repository_access_level
(String) Set the repository access level. Valid values are disabled
, private
, enabled
.repository_storage
(String) Which storage shard the repository is on. (administrator only)request_access_enabled
(Boolean) Allow users to request member access.requirements_access_level
(String) Set the requirements access level. Valid values are disabled
, private
, enabled
.resolve_outdated_diff_discussions
(Boolean) Automatically resolve merge request diffs discussions on lines changed with a push.restrict_user_defined_variables
(Boolean) Allow only users with the Maintainer role to pass user-defined variables when triggering a pipeline.security_and_compliance_access_level
(String) Set the security and compliance access level. Valid values are disabled
, private
, enabled
.shared_runners_enabled
(Boolean) Enable shared runners for this project.skip_wait_for_default_branch_protection
(Boolean) If true
, the default behavior to wait for the default branch protection to be created is skipped.
This is necessary if the current user is not an admin and the default branch protection is disabled on an instance-level.
There is currently no known way to determine if the default branch protection is disabled on an instance-level for non-admin users.
This attribute is only used during resource creation, thus changes are suppressed and the attribute cannot be imported.snippets_access_level
(String) Set the snippets access level. Valid values are disabled
, private
, enabled
.snippets_enabled
(Boolean) Enable snippets for the project.squash_commit_template
(String) Template used to create squash commit message in merge requests. (Introduced in GitLab 14.6.)squash_option
(String) Squash commits when merge request. Valid values are never
, always
, default_on
, or default_off
. The default value is default_off
. [GitLab >= 14.1]suggestion_commit_message
(String) The commit message used to apply merge request suggestions.tags
(Set of String) The list of tags for a project; put array of tags, that should be finally assigned to a project. Use topics instead.template_name
(String) When used without use_custom_template, name of a built-in project template. When used with use_custom_template, name of a custom project template. This option is mutually exclusive with template_project_id
.template_project_id
(Number) When used with use_custom_template, project ID of a custom project template. This is preferable to using template_name since template_name may be ambiguous (enterprise edition). This option is mutually exclusive with template_name
. See gitlab_group_project_file_template
to set a project as a template project. If a project has not been set as a template, using it here will result in an error.timeouts
(Block, Optional) (see below for nested schema)topics
(Set of String) The list of topics for the project.use_custom_template
(Boolean) Use either custom instance or group (with group_with_project_templates_id) project template (enterprise edition).
~> When using a custom template, Group Tokens won't work. You must use a real user's Personal Access Token.visibility_level
(String) Set to public
to create a public project. Valid values are private
, internal
, public
.wiki_access_level
(String) Set the wiki access level. Valid values are disabled
, private
, enabled
.wiki_enabled
(Boolean) Enable wiki for the project.avatar_url
(String) The URL of the avatar image.empty_repo
(Boolean) Whether the project is empty.http_url_to_repo
(String) URL that can be provided to git clone
to clone theid
(String) The ID of this resource.path_with_namespace
(String) The path of the repository with namespace.runners_token
(String, Sensitive) Registration token to use during runner setup.ssh_url_to_repo
(String) URL that can be provided to git clone
to clone theweb_url
(String) URL that can be used to find the project in a browser.container_expiration_policy
Optional:
cadence
(String) The cadence of the policy. Valid values are: 1d
, 7d
, 14d
, 1month
, 3month
.enabled
(Boolean) If true, the policy is enabled.keep_n
(Number) The number of images to keep.name_regex
(String, Deprecated) The regular expression to match image names to delete.name_regex_delete
(String) The regular expression to match image names to delete.name_regex_keep
(String) The regular expression to match image names to keep.older_than
(String) The number of days to keep images.Read-Only:
next_run_at
(String) The next time the policy will run.push_rules
Optional:
author_email_regex
(String) All commit author emails must match this regex, e.g. @my-company.com$
.branch_name_regex
(String) All branch names must match this regex, e.g. (feature|hotfix)\/*
.commit_committer_check
(Boolean) Users can only push commits to this repository that were committed with one of their own verified emails.commit_message_negative_regex
(String) No commit message is allowed to match this regex, for example ssh\:\/\/
.commit_message_regex
(String) All commit messages must match this regex, e.g. Fixed \d+\..*
.deny_delete_tag
(Boolean) Deny deleting a tag.file_name_regex
(String) All committed filenames must not match this regex, e.g. (jar|exe)$
.max_file_size
(Number) Maximum file size (MB).member_check
(Boolean) Restrict commits by author (email) to existing GitLab users.prevent_secrets
(Boolean) GitLab will reject any files that are likely to contain secrets.reject_unsigned_commits
(Boolean) Reject commit when it’s not signed through GPG.timeouts
Optional:
create
(String)delete
(String)Import is supported using the following syntax:
# You can import a project state using `terraform import <resource> <id>`. The
# `id` can be whatever the [get single project api][get_single_project] takes for
# its `:id` value, so for example:
terraform import gitlab_project.example richardc/example
# NOTE: the `import_url_username` and `import_url_password` cannot be imported.