Setup

On the Github integration page in the Hyphen app:

Add Hyphen to your Github organization.
Submit your GitHub Installation ID and Backup Verification Email to connect it to Hyphen. If an integration connection cannot be automatically setup, the backup verification email will be sent a link where it can be verified manually.

Configuration

Field	Type	Description
`installationId`	`number` (required)	Unique installation ID generated when installing an application in GitHub. Used for generating an access token and pulling `githubOrgId` and `githubOrgName`.
`githubOrgId`	`number`	Pulled during the integration setup. Used for reference.
`githubOrgName`	`string`	Pulled during the integration setup. Used for requests that reference this key.
`verificationEmail`	`string` (required)	Backup email address used to verify ownership of a resource when no associated email address is available.

User connections can only connect to existing users in GitHub. If no input is provided to connect to an existing user, the member email will be used.

Prerequisites:

Field	Type	Description
`userId`	`string` (optional)	GitHub username.
`email`	`string`	Public email address of the GitHub user. Defaults to member email in Hyphen if not publicly available.
`orgSlug`	`string`	The `githubOrgName` from the integration configuration.
`profileUrl`	`string`	URL of the GitHub public profile page.

A connection can be created by providing the GitHub username.

Scenario	Action
Public email matches the member email	No verification needed.
Public email does not match the member email	A verification email is sent to the GitHub user email address.
No public email available	A verification email is sent to the integration's backup `verificationEmail`.

These can connect to existing teams in GitHub, or a new team will be created if no input is provided.

Field	Type	Description
`teamSlug`	`string`	Unique team slug in GitHub used for reference in future requests.
`orgSlug`	`string`	The `githubOrgName` from the integration configuration.
`teamName`	`string`	Display name of the team in GitHub.
`teamId`	`number`	Unique team ID in GitHub.

Provide the GitHub team name to create a connection to an existing team.

Scenario	Action
Admin with public email exists	Verification handled by the admin.
No admin with public email	Verification email sent to the integration's backup `verificationEmail`.

A User connection will be added as the default “Member” role when added to the team.

These can connect to existing repositories in GitHub, or a new repository will be created if no input is provided.

Field	Type	Description
`repositoryId`	`string`	Unique repository ID in GitHub.
`orgSlug`	`string`	The `githubOrgName` from the integration configuration.
`repositoryName`	`string`	Repository name in GitHub for display and reference.

Provide the GitHub repository name to create a connection to an existing repository.

A verification email is sent to the integration's verificationEmail for existing repositories.

A Team connection will be added as a “Maintain” role when added to the code repository.

These can connect to existing projects in GitHub, or a new project will be created if no input is provided.

Field	Type	Description
`id`	`string`	Unique project ID in GitHub.
`projectSlug`	`string`	GitHub project number used for reference in future requests.
`orgSlug`	`string`	The `githubOrgName` from the integration configuration.
`repositoryName`	`string`	Repository name in GitHub for display and reference.

Provide the GitHub project slug to create a connection to an existing project.

A verification email is sent to the integration's verificationEmail for existing projects.

A Team connection will be added as a “Read” role when added to the project.