GitHub Connection

Hanzo KMS will use a GitHub App with finely grained permissions to connect to GitHub.

Using the GitHub integration with app authentication on a self-hosted instance of Hanzo KMS requires configuring an application on GitHub and registering your instance with it.

Navigate to the GitHub app settings here. Click New GitHub App.

Give the application a name, a homepage URL (your self-hosted domain i.e. https://your-domain.com), and a callback URL (i.e. https://your-domain.com/organization/app-connections/github/oauth/callback).

Enable request user authorization during app installation.

Disable webhook by unchecking the Active checkbox.

Set the repository permissions as follows: Metadata: Read-only, Secrets: Read and write, Environments: Read and write, Actions: Read.

Similarly, set the organization permissions as follows: Secrets: Read and write.

Create the Github application.

If you have a GitHub organization, you can create an application under it in your organization Settings > Developer settings > GitHub Apps > New GitHub App.

Generate a new Client Secret for your GitHub application.

Generate a new Private Key for your Github application.

Obtain the necessary Github application credentials. This would be the application slug, client ID, app ID, client secret, and private key.

Back in your Hanzo KMS instance, you can configure the GitHub App credentials in one of two ways:

Option 1: Server Admin Panel (Recommended)

Navigate to the server admin panel > Integrations > GitHub App and enter the GitHub application credentials:

• Client ID: The Client ID of your GitHub application
• Client Secret: The Client Secret of your GitHub application
• App Slug: The Slug of your GitHub application (found in the URL)
• App ID: The App ID of your GitHub application
• Private Key: The Private Key of your GitHub application

Option 2: Environment Variables

Alternatively, you can add the new environment variables for the credentials of your GitHub application:

• INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID: The Client ID of your GitHub application.
• INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET: The Client Secret of your GitHub application.
• INF_APP_CONNECTION_GITHUB_APP_SLUG: The Slug of your GitHub application. This is the one found in the URL.
• INF_APP_CONNECTION_GITHUB_APP_ID: The App ID of your GitHub application.
• INF_APP_CONNECTION_GITHUB_APP_PRIVATE_KEY: The Private Key of your GitHub application.

Once configured, you can use the GitHub integration via app authentication. If you configured the credentials using environment variables, restart your Hanzo KMS instance for the changes to take effect. If you configured them through the server admin panel, allow approximately 5 minutes for the changes to propagate.

Setup GitHub Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.

Select the GitHub Connection option from the connection options modal.

Select the GitHub App method and click Connect to GitHub.

You may optionally configure GitHub Enterprise options:

• Gateway: The gateway connected to your private network
• Hostname: The hostname at which to access your GitHub Enterprise instance

You will then be redirected to the GitHub app installation page.

Install and authorize the GitHub application. This will redirect you back to Hanzo KMS's App Connections page.

Your GitHub Connection is now available for use.

Hanzo KMS will use an OAuth App to connect to GitHub.

Using the GitHub integration on a self-hosted instance of Hanzo KMS requires configuring an OAuth application in GitHub and registering your instance with it.

Navigate to your user Settings > Developer settings > OAuth Apps to create a new GitHub OAuth application.

Create the OAuth application. As part of the form, set the Homepage URL to your self-hosted domain https://your-domain.com and the Authorization callback URL to https://your-domain.com/organization/app-connections/github/oauth/callback.

If you have a GitHub organization, you can create an OAuth application under it in your organization Settings > Developer settings > OAuth Apps > New Org OAuth App.

Obtain the Client ID and generate a new Client Secret for your GitHub OAuth application.

Back in your Hanzo KMS instance, add two new environment variables for the credentials of your GitHub OAuth application:

• INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID: The Client ID of your GitHub OAuth application.
• INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET: The Client Secret of your GitHub OAuth application.

Once added, restart your Hanzo KMS instance and use the GitHub integration.

Setup GitHub Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.

Select the GitHub Connection option from the connection options modal.

Select the OAuth method and click Connect to GitHub.

You will then be redirected to the GitHub to grant Hanzo KMS access to your GitHub account (organization and repo privileges). Once granted, you will redirect you back to Hanzo KMS's App Connections page.

Your GitHub Connection is now available for use.

Hanzo KMS will use a Personal Access Token to connect to GitHub.

Create a Personal Access Token

Navigate to your user Settings > Developer settings > Personal Access Tokens to create a new Personal Access Token.

Click Generate new token to create the token.

Fill in the Personal Access Token details:

• Token name: A descriptive name for the token (e.g., "kms-connection-token")
• Repository access: Select the repositories you want to grant access to
  • Select All repositories or Only selected repositories to be able to manage the secrets in the selected repositories.
• Select scopes: Add the following scopes:
  • Metadata: Read-only
  • Environments: Read and write
  • Secrets: Read and write

Click Generate token to create the token.

Copy the generated token immediately as it won't be shown again.

Keep your Personal Access Token secure and do not share it. Anyone with access to this token can access your GitHub account and repositories.

Setup GitHub Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.

Select the GitHub Connection option from the connection options modal.

Select the Personal Access Token method and fill in the Personal Access Token field with your Personal Access Token.

You may optionally configure GitHub Enterprise options:

• Gateway: The gateway connected to your private network
• Hostname: The hostname at which to access your GitHub Enterprise instance

Click Create Connection.

Your GitHub Connection is now available for use.