Setup

1. Create or sign into your Google Cloud account

2. Connect your Google Cloud organization to Hyphen

Sign in with your Google account
Select the GCP organization you wish to connect
(Optional) Select a billing account

That's it! After you've completed these steps, Hyphen will automatically:

Verify the credentials and selected organization
Grant necessary permissions to the Hyphen service
Configure the domain-restricted sharing policy to allow access from Hyphen

Required Permissions

The one-click installation requires the following permissions:

resourcemanager.organizations.getIamPolicy
resourcemanager.organizations.setIamPolicy
resourcemanager.organizations.get
billing.accounts.list
orgpolicy.policies.create
orgpolicy.policies.update
orgpolicy.policies.get
orgpolicy.policies.list
resourcemanager.tagKeys.create
resourcemanager.tagKeys.get
resourcemanager.tagKeys.list
resourcemanager.tagValues.create
resourcemanager.tagValues.get
resourcemanager.tagValues.list

Required OAuth Scopes

To perform the setup and ongoing management securely, Hyphen requires access to specific Google Cloud scopes:

`https://www.googleapis.com/auth/cloud-platform`

This broad scope allows Hyphen to manage resources across your GCP organization. It is required to:

List organizations
Set the domain restricted sharing policy
Assign roles to the Hyphen service account, including:
- Organization Administrator
- Folder Creator
- Project Creator
- Artifact Registry Administrator
- Compute Network Admin
- Cloud Run Admin
- Service Usage Admin
- Billing Account User

These roles are necessary to let Hyphen create and manage GCP projects and resources on your behalf.

`https://www.googleapis.com/auth/cloud-billing.readonly`

This scope allows Hyphen to:

List available billing accounts

This is optional but recommended to allow you to associate a billing account during project creation.

Connections

Permission Group

Permission group connections correspond to Google Workspace distribution lists and require an existing Google Workspace integration within the Hyphen organization. Connections can link to existing Groups in Google Workspace, or a new group will be created if no input is provided.

If a distribution list already exists for the same resource in Google Workspace, it will be used as the Permission Group connection.

When creating a new Group in Google Workspace, the Hyphen team name will be used as the group name.

Configuration

Field	Type	Description
`groupId`	`string`	Unique group ID in Google Workspace.
`groupName`	`string`	Display name of the group in Google Workspace.
`groupEmail`	`string`	Unique group email used for reference in future requests.

Connection Input

Provide the Google Workspace group email to create a connection to an existing Group.

Verification

Scenario	Action
Group has an owner	Verification handled by the owner.
No owner exists	A verification email is sent to the group email.

Folder

Folder connections can link to existing folders in Google Cloud, or a new folder will be created if no input is provided.

When creating a new folder in Google Cloud, the Hyphen project name will be used as the folder name, adjusted to include only alphanumeric characters.

Configuration

Field	Type	Description
`folderId`	`string`	Unique folder ID in Google Cloud.
`folderPath`	`string`	Path in the format `folders/{folderId}`.
`folderName`	`string`	Display name of the folder in Google Cloud.

Connection Input

Provide the Google Cloud folder ID to create a connection to an existing Folder.

Cloud Workspace

Cloud Workspace connections can link to existing projects in Google Cloud, or a new project will be created if no input is provided.

A Google Cloud project relies on a Folder. If no Folder connection exists for the Hyphen project, a new Folder will be created.

When creating a new project in Google Cloud, the project name will combine the Hyphen project name and the Hyphen project environment name.

Configuration

Field	Type	Description
`projectId`	`string`	Unique project ID in Google Cloud.
`projectPath`	`string`	Path in the format `projects/{projectId}`.
`projectName`	`string`	Display name of the project in Google Cloud.

Connection Input

Provide the Google Cloud project ID to create a connection to an existing Project.

Access

A Team connection will be added with the "Owner" role when added to the project.

User

User connections correspond to Google Workspace users and require an existing Google Workspace integration within the Hyphen organization.

User connections can only link to existing users in Google Workspace. If no input is provided, the member email will be used to locate the user.

Configuration

Field	Type	Description
`userId`	`string`	Unique user ID in Google Workspace.
`email`	`string`	Unique user email in Google Workspace.

Connection Input

A connection to an existing user can be created by providing the user email.

Test Connect