Organizing Workspaces with Projects

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. 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 Organize Workspaces with Projects tutorial.

Permissions

You must be a member of a team with Manage all projects and Manage all workspaces organization-level permissions permissions to create a project.

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 all 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 all projects" permission or the admin role for the project they wish to use.

View Projects

To view your organization's projects:

1. Click Projects & workspaces.
2. Click the left chevron icon next to Workspaces to open the project drawer.
3. Click the icon again to close the drawer.

To view the workspaces in a specific project:

1. Click Projects & workspaces.
2. Click the left chevron icon next to Workspaces to open the project drawer.
3. Click the project you want to review. Terraform Cloud now displays only the workspaces in the selected project.

Create a Project

To create a new project:

1. Click Projects & workspaces.
2. Click New and choose Project from the dropdown menu. The Create a new project modal appears.
3. Enter a Project Name. The name must be unique within the organization and can only include letters, numbers, inner spaces, dashes (-), and underscores (_).
4. Click Create.

The project drawer displays the new project in the projects list.

Edit a Project

To edit a project:

1. Click Projects & workspaces.
2. Click the left chevron icon next to Workspaces to open the project drawer.
3. Hover your cursor over the project you want to edit. An edit button appears to the right of the project name.
4. Click the edit button.

On this settings page, you can update the project name, modify team access to the project, and delete the project.

Search for a Project

If your organization has more than 20 projects, you may need to use the search function to find it in the list.

To search for a project:

1. Click Projects & workspaces.
2. Click the left chevron icon next to Workspaces to open the project drawer.
3. Click the magnifying glass next to Projects.
4. Type your project name.

Move a Workspace to a Different Project

You can update the project a workspace belongs to from the workspace's settings page or from the Projects and Workspaces view. These workflows are only available once your organization has multiple projects. The user must have admin permissions on both the source and destination project to move a workspace, either through the "Manage Workspaces & Projects" organization permission, or explicit team admin privileges for both projects. Keep in mind that moving a workspace to another project may affect user visibility for the workspaces in the project.

To move a workspace to a different project from the Projects and Workspaces view:

1. Click Projects & workspaces.
2. Hover your cursor over the workspace you want to move. A (...) button appears on the right side of the list item.
3. Click the (...) button. A dropdown menu appears.
4. Click Change project. A Move workspace modal appears.
5. Select the Destination project from the project selector. If your organization has many projects, you may need to search for the target project.
6. Click Move.

The workspace is now under a different project.

Delete a Project

You can only delete projects that do not contain workspaces.

To delete an empty project:

1. Click Projects & workspaces.
2. Click the left chevron icon next to Workspaces to open the project drawer.
3. Hover your cursor over the project you want to delete. An edit button appears to the right of the project name.
4. Click the edit button. The settings view for the selected project appears.
5. Click the Delete button. A Delete project modal appears.
6. Click the Delete button to confirm the deletion.

Terraform Cloud will return to the Projects and workspaces view with the deleted project removed from the list.