Create or claim a namespace

Organizations can create or claim a GitHub account’s public registry namespace to allow its members to manage the public registry artifacts in that account.

When an organization claims a namespace, the only way to manage that claimed namespace is through HCP Terraform, meaning you can no longer manage that namespace through the public registry.

Requirements

You must meet the following requirements to claim a namespace for an organization:

• Be a member of the owners team in your HCP Terraform organization.
• If the namespace you want to claim has existing public registry artifacts, you must:
  • Have write access to each artifact’s corresponding repository.
  • Each repository must have the Terraform Cloud GitHub App installed.

Install the GitHub App

You must install the Terraform Cloud GitHub App into the GitHub account with the namespace you want to claim. To install a GitHub app, you must own your account or receive administrator approval for your organization account.

During the Terraform Cloud GitHub App installation process, you can choose to install the app in specific repositories or globally in every repository in your account. We recommend installing the Terraform Cloud GitHub App globally into every repository in your account to simplify claiming a namespace with existing public registry artifacts and publishing future artifacts.

Workflow

To create or claim a namespace:

1. Sign in to HCP Terraform and navigate to the organization where you want to create or claim a namespace.
2. In the sidebar navigate to Registry, then Public namespaces.
3. Click New Namespace.
4. HCP Terraform lists accounts where you installed the Terraform Cloud GitHub App. Choose the account you want to create or claim the namespace of.
5. After selecting an account, HCP Terraform verifies if you qualify to claim that namespace.
   • If the namespace already exists and contains artifacts, then HCP Terraform ensures you have write access to each artifact’s corresponding repository.
6. Click Create Namespace or Claim Namespace to finalize your organization’s public namespace ownership.

After claiming or creating a new namespace, the Public namespace page lists any artifacts your organization now controls under that namespace.

If HCP Terraform does not list the GitHub account you want to claim on the New namespace page, click Add GitHub Account and follow the prompts to reinstall the application. After reinstalling, sign into GitHub as a user with access to the account you want to claim and try again. For more information on any specific error codes you encounter, refer to the GitHub documentation.