Overview

Projects let you organize your workspaces and scope access to workspace resources. Each project has a separate permissions set that you can use to grant teams access to all workspaces in the project, defining access control boundaries for teams and their resources. Project-level permissions are more granular than organization-level permissions, but more specific than individual workspace-level grants.

When deciding how to structure your projects, consider which groups of resources need distinct access rules. You may wish to define projects by business units, departments, subsidiaries, or technical teams.

Hands On: Try our Managing Projects tutorial.

Default Project

Every workspace must belong to exactly one project. By default, all workspaces belong to an organization's Default Project. You can rename the default project, but you cannot delete it. You can specify a workspace's project at the time of creation and move it to a different project later.

The “Manage Workspaces” team permission lets users create and manage workspaces. Users with this permission can read and manage all workspaces, but new workspaces are automatically added to the “Default Project” and users cannot access the metadata for other projects. To create workspaces under other projects, users also need the "Manage Projects & Workspaces" permission or the admin role for the project they wish to use.

Managing Projects

The "Manage all Projects" team permission lets users manage projects. Users with this permission can view, edit, delete, and assign team access to all of an organization's projects. Refer to Managing Projects for more details.

Default Execution Mode

By default, a project uses the organization's default execution mode to choose the execution platform for a project. Alternatively, you can instead choose a custom execution mode for a project.

Specifying the "Remote" execution mode instructs HCP Terraform to perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more.

To disable remote execution for a project, change its execution mode to "Local". This mode lets you perform Terraform runs locally with the CLI-driven run workflow.

If you instead need to allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure, consider using HCP Terraform agents. By deploying a lightweight agent, you can establish a simple connection between your environment and HCP Terraform.

Changing your project's execution mode after a run has already been planned will cause the run to error when it is applied.

To minimize the number of runs that error when changing your project's execution mode, you should:

1. Disable auto-apply if you have it enabled.
2. Complete any runs that are no longer in the pending stage.
3. Lock your workspace to prevent any new runs.
4. Change the execution mode.
5. Enable auto-apply, if you had it enabled before changing your execution mode.
6. Unlock your workspace.