🔷 Azure DevOps Project Terraform Module

The foundation composite of the Azure DevOps suite — an Azure DevOps project plus its features, pipeline security settings, tags, and project-level permissions, behind one deeply-typed, organization-scoped boundary. Its project_id is the recurring wire-in for nearly every other module. Built for azuredevops v1.x.

This module provisions an Azure DevOps project and the core settings that travel with it:

• 🏗️ The project (azuredevops_project) — name, description, visibility, version control, and work-item process. Secure-by-default: private + Git + Agile.
• 🎛️ Features (azuredevops_project_features) — toggle Boards, Repos, Pipelines, Test Plans, and Artifacts on or off.
• 🛡️ Pipeline settings (azuredevops_project_pipeline_settings) — job-scope enforcement, repo-scoped tokens, settable-var limits, badge privacy.
• 🏷️ Tags (azuredevops_project_tags) — project labels (NOT the azurerm tags pattern).
• 🔐 Permissions (azuredevops_project_permissions) — project-level ACLs assigned to group principals, default-deny.

💡 Why it matters: every other module in the suite (git_repository, variable_group, build_definition, branch_policies, …) wires from this module's project_id. Making the project and its baseline settings a single, reviewable, version-pinned unit means the foundation is consistent and secure before anything else is built on top of it.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

terraform-azuredevops-project is the root of the dependency graph. Almost everything flows from its project_id.

flowchart TD
 project["terraform-azuredevops-project"]
 repo["terraform-azuredevops-git-repository"]
 vg["terraform-azuredevops-variable-group"]
 build["terraform-azuredevops-build-definition"]
 bpol["terraform-azuredevops-branch-policies"]
 rpol["terraform-azuredevops-repository-policies"]
 env["terraform-azuredevops-environment"]
 se["terraform-azuredevops-serviceendpoint-azure"]

 project -->|project_id| repo
 project -->|project_id| vg
 project -->|project_id| build
 project -->|project_id| bpol
 project -->|project_id| rpol
 project -->|project_id| env
 project -->|project_id| se
 repo -->|repository_id| build

 style project fill:#8957E5,color:#fff

The keystone azuredevops_project.this (purple) creates the project; its id feeds project_id into four for_each children. The three singleton children render 0-or-1 via a guarded for_each; permissions is a true keyed collection.

flowchart TD
 this["azuredevops_project<br/>(this) — keystone (creates the project)"]
 feat["azuredevops_project_features<br/>for_each (0-or-1, var.features)"]
 pset["azuredevops_project_pipeline_settings<br/>for_each (0-or-1, var.pipeline_settings)"]
 tags["azuredevops_project_tags<br/>for_each (0-or-1, var.tags)"]
 perm["azuredevops_project_permissions<br/>for_each var.permissions"]

 this -->|project_id = this.id| feat
 this -->|project_id = this.id| pset
 this -->|project_id = this.id| tags
 this -->|project_id = this.id| perm

 style this fill:#8957E5,color:#fff

Resource inventory

• azuredevops_project.this — the project (primary this).
• azuredevops_project_features.this — guarded for_each; present when var.features != null.
• azuredevops_project_pipeline_settings.this — guarded for_each; present when var.pipeline_settings != null.
• azuredevops_project_tags.this — guarded for_each; present when length(var.tags) > 0.
• azuredevops_project_permissions.this — for_each over var.permissions.

The module declares the provider requirement only — it configures no provider {} block. The root/spec configures the organization URL and credentials (PAT or Azure AD service principal).

⚠️ Creating a project — and changing its visibility — requires Project Collection Administrator or Organization Owner. Assigning project-level ACLs requires at least Project Administrators; setting permissions on the collection-level node requires Project Collection Administrators. These are not held by Contributors by default — grant them to the Terraform identity deliberately.

terraform-azuredevops-project/
├── providers.tf # azuredevops >= 1.0, < 2.0; no provider {} block
├── variables.tf # name → project config → features/pipeline_settings/tags/permissions → timeouts
├── main.tf # azuredevops_project.this + 4 for_each children
├── outputs.tf # id, project_id, name, state passthrough, per-collection maps
├── SCOPE.md # cross-module contract + required scopes/auth + gotchas
└── README.md # this file

Smallest working call — a secure-by-default private Git project:

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"

  name = "Payments"
  # visibility = "private", version_control = "Git", work_item_template = "Agile" by default
}

Then wire module.project.project_id into every project-scoped sibling module.

This module is organization-scoped — it has no project_id input. The keystone creates the project; its id becomes the project_id everything else consumes. The only configuration "consumed" is the provider's organization URL + credentials, set at the root.

🔒 No sensitive outputs — this resource family carries no secrets. The module emits IDs and state attributes only.

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"
}

module "project" {
  source      = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name        = "Payments"
  description = "Core payments platform — managed by Terraform."
}

module "project" {
  source             = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name               = "Payments"
  work_item_template = "Scrum" # "Agile" (default) | "Basic" | "CMMI" | "Scrum" | a custom inherited process
}

module "project" {
  source             = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name               = "Payments"
  work_item_template = "" # empty string → inherit the org default process
}

module "project" {
  source          = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name            = "LegacyTfvc"
  version_control = "Tfvc" # IMMUTABLE — forces recreate if changed
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"

  features = {
    boards       = "enabled"
    repositories = "enabled"
    pipelines    = "enabled"
    testplans    = "disabled"
    artifacts    = "disabled"
  }
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"

  # Empty object applies the hardened defaults (all enforce_* = true, badges private,
  # metadata not published). Override individual fields as needed.
  pipeline_settings = {}
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"

  pipeline_settings = {
    enforce_job_scope                    = true
    enforce_referenced_repo_scoped_token = true
    enforce_settable_var                 = true
    publish_pipeline_metadata            = false
    status_badges_are_private            = true
    enforce_job_scope_for_release        = true
  }
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"
  tags   = ["business-critical", "pci", "team-payments"]
}

data "azuredevops_group" "contributors" {
  project_id = module.project.project_id
  name       = "Contributors"
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"

  permissions = {
    contributors_lockdown = {
      principal = data.azuredevops_group.contributors.id
      permissions = {
        DELETE            = "Deny"
        RENAME            = "Deny"
        UPDATE_VISIBILITY = "Deny"
        GENERIC_READ      = "Allow"
      }
    }
  }
}

permissions = {
  grant_admins = {
    principal = data.azuredevops_group.admins.id
    permissions = {
      MANAGE_PROPERTIES = "Allow"
      CHANGE_PROCESS    = "Allow"
    }
    replace = false # merge with the group's existing ACL instead of replacing it
  }
}

permissions = {
  readers = {
    principal   = data.azuredevops_group.readers.id
    permissions = { GENERIC_READ = "Allow", DELETE = "Deny" }
  }
  build_admins = {
    principal   = data.azuredevops_group.build_admins.id
    permissions = { ADMINISTER_BUILD = "Allow", START_BUILD = "Allow" }
  }
}

module "project" {
  source = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name   = "Payments"

  timeouts = {
    create = "10m"
    delete = "10m"
  }

  # per-child timeouts also supported on features / pipeline_settings / permissions entries
  features = {
    pipelines = "enabled"
    timeouts  = { create = "10m" }
  }
}

data "azuredevops_group" "contributors" {
  project_id = module.project.project_id
  name       = "Contributors"
}

module "project" {
  source             = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name               = "Payments"
  description        = "Core payments platform — managed by Terraform."
  visibility         = "private"
  version_control    = "Git"
  work_item_template = "Agile"

  features = {
    boards       = "enabled"
    repositories = "enabled"
    pipelines    = "enabled"
    testplans    = "disabled"
    artifacts    = "enabled"
  }

  pipeline_settings = {} # hardened defaults
  tags              = ["pci", "team-payments"]

  permissions = {
    contributors = {
      principal   = data.azuredevops_group.contributors.id
      permissions = { GENERIC_READ = "Allow", DELETE = "Deny" }
    }
  }
}

module "project" {
  source             = "git::https://github.com/microsoftexpert/terraform-azuredevops-project?ref=v1.0.0"
  name               = "Payments"
  description        = "Core payments platform."
  visibility         = "private"
  version_control    = "Git"
  work_item_template = "Agile"

  features          = { artifacts = "enabled", testplans = "disabled" }
  pipeline_settings = {} # hardened defaults
}

module "repo" {
  source         = "git::https://github.com/microsoftexpert/terraform-azuredevops-git-repository?ref=v1.0.0"
  name           = "payments-api"
  project_id     = module.project.project_id # ← the headline wire-in
  default_branch = "refs/heads/main"
}

module "branch_policies" {
  source        = "git::https://github.com/microsoftexpert/terraform-azuredevops-branch-policies?ref=v1.0.0"
  project_id    = module.project.project_id
  repository_id = module.repo.repository_id
}

module "build" {
  source        = "git::https://github.com/microsoftexpert/terraform-azuredevops-build-definition?ref=v1.0.0"
  name          = "payments-api-ci"
  project_id    = module.project.project_id
  repository_id = module.repo.repository_id
}

object({
 boards = optional(string) # "enabled" | "disabled"
 repositories = optional(string)
 pipelines = optional(string)
 testplans = optional(string)
 artifacts = optional(string)
 timeouts = optional(object({ create, read, update, delete }))
})

object({
 enforce_job_scope = optional(bool, true)
 enforce_referenced_repo_scoped_token = optional(bool, true)
 enforce_settable_var = optional(bool, true)
 publish_pipeline_metadata = optional(bool, false)
 status_badges_are_private = optional(bool, true)
 enforce_job_scope_for_release = optional(bool, true)
 timeouts = optional(object({ create, read, update, delete }))
})

map(object({
 principal = string # group descriptor (required)
 permissions = map(string) # name => "Allow" | "Deny" | "NotSet"
 replace = optional(bool, true)
 timeouts = optional(object({ create, read, update, delete }))
}))

ℹ️ No sensitive outputs — the module emits IDs and state attributes only. This resource family carries no secrets.

• Organization-scoped keystone. Unlike most of the suite, azuredevops_project takes no project_id — it creates the project, and its own id IS the project_id consumed downstream. The four children wire project_id = azuredevops_project.this.id.
• Features managed one way only. The provider forbids managing features via both the keystone's inline features block and azuredevops_project_features. This module leaves the inline block unset and manages features solely through the dedicated resource — set only the features you want to manage.
• Public projects are retired. New public projects can no longer be created (only orgs grandfathered on the legacy Allow public project policy), and existing public projects auto-convert to private in 2027. visibility defaults to private, and public → private is one-way.
• Process & version control are effectively immutable. Changing work_item_template (process) or version_control after creation forces destroy/recreate. process_template_id is computed (read-only) and surfaced as an output.
• Pipeline settings: org overrides project. Organization-level pipeline settings win. Setting a field false here when the org enforces it true produces a perpetual diff — manage that field at the org instead.
• Permissions are group-scoped and inherited. ACLs target group descriptors, never individual users; security groups are managed at the org/collection level even when scoped to a project. A Deny at any level beats an Allow — favour NotSet (inherit) and Deny over blanket Allow.
• Eventual consistency. Project creation is eventually consistent — dependent resources may briefly 404 right after apply, and a just-created group referenced in permissions may need a retry as identity propagation completes.
• Version control note. Azure Repos Git is browse/clone over HTTPS only — SSH and GVFS endpoints are unavailable for the connected experience.

• Type is the contract — deeply-typed object schemas (features and pipeline_settings are typed objects, not loose maps); a malformed input is a plan-time type error.
• One keystone this + four for_each children — singletons render 0-or-1 via guarded for_each, permissions is a keyed collection — no count.
• optional with secure defaults — visibility = "private", version_control = "Git", work_item_template = "Agile", and hardened pipeline-settings defaults (enforce_* = true, badges private).
• validation {} for closed sets — visibility, version_control, feature values (enabled/disabled), permission action values (Allow/Deny/NotSet), and the full project permission name set. work_item_template is intentionally not enum-validated because custom inherited processes are allowed.
• dynamic + try(x, null) make main.tf a total renderer; optional blocks render only when set.
• id + project_id are the primary outputs (never object_id).

cd C:\GitHubCode\newazuredevopsmodules\terraform-azuredevops-project
terraform init -backend=false
terraform validate
terraform fmt -check

terraform plan / apply require live organization credentials (org URL + PAT, or an Azure AD service principal) with Project Collection Administrator rights to create projects. The offline gate above is sufficient for structural correctness. For live testing, use a non-production Azure DevOps organization with a dedicated identity — never the production org.

• ✅ terraform init -backend=false — provider microsoft/azuredevops v1.15.x installed.
• ✅ terraform validate — Success! The configuration is valid.
• ✅ terraform fmt -check — clean, no diff.
• 🔬 Live integration (optional, non-production org only): apply, then confirm via the Azure DevOps web portal or the read-only ADO MCP that the project, features, pipeline settings, tags, and ACLs landed as expected.

Outputs:

id = "11111111-2222-3333-4444-555555555555"
project_id = "11111111-2222-3333-4444-555555555555"
name = "Payments"
visibility = "private"
version_control = "Git"
work_item_template = "Agile"
process_template_id = "adcc42ab-9882-485e-a3ed-7678f01f66bc"
features = { artifacts = "enabled", testplans = "disabled" }
pipeline_settings_id = "11111111-2222-3333-4444-555555555555"
tags = ["pci", "team-payments"]
permission_ids = { contributors = "..." }

• azuredevops_project
• azuredevops_project_features
• azuredevops_project_pipeline_settings
• azuredevops_project_tags
• azuredevops_project_permissions
• About projects and scaling your organization
• Public projects retirement
• Project-level permissions reference
• About process customization and inherited processes
• Sibling modules: terraform-azuredevops-git-repository, terraform-azuredevops-variable-group, terraform-azuredevops-build-definition, terraform-azuredevops-branch-policies

💙 "Infrastructure as Code should be standardized, consistent, and secure."