Skip to main content
As your organization adopts HCP Terraform (Terraform Cloud) and the number of workspaces grows, a single flat list of workspaces becomes hard to manage. This guide explains how Projects help you scale workspace administration by grouping related workspaces, applying shared settings, and scoping team permissions. When workspaces are all listed together—networking-dev, web-prod, customer-data, monitoring-qa, etc.—you encounter several operational challenges:
  • Discovery becomes harder: lists with dozens or hundreds of workspaces slow down finding the right one.
  • Repetitive changes are error-prone: updating variables or permissions per-workspace doesn’t scale.
  • Team boundaries blur: everyone sees the same global list with no natural separation.
  • Duplication and inconsistency: teams recreate identical variable configurations (for example, provider credentials) across many workspaces.
Projects solve these problems by grouping related workspaces and enabling shared configuration and scoped permissions.
The image is a diagram titled "Workspace Organization," categorizing different projects into Development, Quality Assurance, and Production sections, each with specific project names.
In the diagram above, twelve workspaces are organized into three projects—Development, Quality Assurance, and Production. Grouping provides a clear home for each team’s workspaces and lets administrators apply permissions and shared settings at the project level rather than repeating them across individual workspaces. Organizational hierarchy (bottom-up)
The image illustrates an organizational structure in HashiCorp Terraform Cloud, consisting of three levels: Organization, Project, and Workspace, each with a brief description of their role and functionality.
Key project behaviors and best practices
  • Every workspace belongs to exactly one project.
    • Workspaces cannot be in multiple projects or outside a project; each workspace is assigned to one and only one project.
  • A default project is created for every organization.
    • HCP Terraform creates a default project on organization creation. You may rename it, but you cannot delete it.
    The default project guarantees every workspace has a project. Rename it to match your naming conventions, but note it cannot be removed.
  • Scoped team permissions:
    • Grant teams access at the project level instead of on each workspace. Any current or future workspace added to that project inherits the project-level permissions automatically.
  • Project-level variable sets:
    • Attach variable sets (or organization variable sets) to the project so they apply to current and future workspaces in that project. This reduces duplication and enforces consistency.
  • Execution mode inheritance:
    • The organization defines an execution-mode default (remote, local, or agent). Projects can adopt sensible defaults for their workspaces, while individual workspaces retain the ability to override execution mode when needed.
  • Moving workspaces:
    • Move workspaces between projects to reflect team reorganizations or shifting responsibilities without re-creating the workspace.
  • Infrastructure-as-code for project assignments:
  • Deleting projects:
    • A project must be empty before it can be deleted. Move or delete workspaces in a project prior to removing the project to avoid accidental orphaning of workspaces.
    Only empty projects can be deleted. Always reassign or remove workspaces before attempting to delete a project.
The image shows a diagram with stacked blocks labeled "Organization," "Project," and "Workspace," alongside text explaining execution mode inheritance and project management in Terraform.
Project benefits at a glance Summary Projects are the organizational layer between your organization and individual workspaces in Terraform Cloud/HCP Terraform. They reduce workspace sprawl by providing grouping, scoped permissions, shared variable sets, and execution-mode inheritance—making workspace management more scalable, consistent, and secure. Next steps / walkthrough A follow-up walkthrough demonstrates how to:
  • Create a new project,
  • Assign existing workspaces to a project,
  • Move workspaces between projects, and
  • Attach project-level variable sets.
Links and references

Watch Video