Introduction

Nimbus built integrations with GitHub to seamlessly automate development workflow.

In this documentation, we will show you how to

create a GitHub app

generate client secrets + private key which will be needed to integrate with Nimbus

With those variables, the self-hosted Nimbus solution will be able to integrate with your Github so that your engineers can be authenticated automatically via their Github account without it manually managing ssh keys.

Prerequisites

Make sure you have an HTTPS domain name (for example https://nimbus.company.com) that you use to access Nimbus. In this doc, this domain will be referred to as “<nimbus_url>”

Create a GitHub App

Scroll all the way down. In Developer Settings, select “GitHub Apps”

Create GitHub App

“GitHub App name” section: input any name you’d like, for example, “Nimbus”
“Homepage URL” section: put the domain where you access the Nimbus app
“Callback URL” section: <nimbus_url>/oauth/github/callback
Leave “Expire user authorization tokens” checked
Leave “Request user authorization (OAuth) during installation” and “Enable Device Flow” unchecked
“Setup URL” section: <nimbus_url>/oauth/github/callback

This is the same as the “Callback URL”

Leave “Redirect on update” unchecked
Uncheck the “Active” checkbox in the Webhook section
In the Permissions section:

Repository permissions:

Actions: Read + Write
Content: Read-only

Organization permissions:

No change

Account permissions:

Email addresses: Read-only

In the section “where can this GitHub App be installed?”

Choose “Any account”

Click “Create GitHub App”

Create client secret and private key

After you clicked the “Create GitHub App” button, a new GitHub app will be created, and you will be redirected to the app detail page.

On this page, you will see several pieces of information:

App ID: in the screenshot above, it’s 5. We refer to it by <github_app_id>

Client ID: in the screenshot above, it’s under the App ID. We refer to it by <github_client_id>

Public Link: the public link looks like “https://github.com/apps/<github_app_name>”. For GitHub Enterprise servers, it looks like “https://<domain>/github-apps/<github_app_name>”

Note the <github_app_name> here, which we will use in a later section

Callback URL: we refer to it by <github_oauth_redirect_url>

Now we will proceed to two more setup steps:

Generate a new client's secret

And save the secret string, we will refer to it by <github_client_secret> here.

Scroll all the way down, and generate a private key

And remember where the pem file is downloaded, we will refer to the file path by <github_app_private_key>

Note this is a file path in your local laptop, which will be passed into k8s secret by “--from-file” flag

Collect information for Kubernetes secrets

Name	Value	Description
GITHUB_API	See Description	If you are using GitHub Enterprise Server, this is the URL pointing to your GitHub instances. Otherwise, leave this as an empty string
GITHUB_APP_ID	<github_app_id>
GITHUB_APP_NAME	<github_app_name>
GITHUB_APP_PRIVATE_KEY	<github_app_private_key>
GITHUB_CLIENT_ID	<github_client_id>
GITHUB_CLIENT_SECRET	<github_client_secret>
GITHUB_ENCRYPT_KEY	See Description	It’s a random string with size 32, which Nimbus is using to encrypt GitHub-related credentials in the database. You can type any random string into it
GITHUB_OAUTH_REDIRECT_URI	<github_oauth_redirect_url>

Update Kubernetes secrets

plain text
kubectl -n nimbus create secret generic nimbus-alpine-secrets \    
--from-literal=ENT_DATASOURCE='postgresql://root@cockroachdb-public:26257/nimbus?application_name=alpine&connect_timeout=15&sslcert=/cockroach/cockroach-certs/client.root.crt&sslkey=/cockroach/cockroach-certs/client.root.key&sslmode=verify-full&search_path=public&sslrootcert=/cockroach/cockroach-certs/ca.crt' \    
--from-literal=GITHUB_API='<github_api>' \    
--from-literal=GITHUB_APP_ID='<github_app_id>' \    
--from-literal=GITHUB_APP_NAME='<github_app_name>' \    
--from-file=GITHUB_APP_PRIVATE_KEY='<github_app_private_key_path>' \    
--from-literal=GITHUB_CLIENT_ID='<github_client_id>' \    
--from-literal=GITHUB_CLIENT_SECRET='<github_client_secret>' \    
--from-literal=GITHUB_ENCRYPT_KEY='<github_encrypt_key>' \    
--from-literal=GITHUB_OAUTH_REDIRECT_URI='<github_oauth_redirect_uri>' \    
--from-literal=DB_URL='postgresql://root@cockroachdb-public:26257/nimbus?application_name=alpine&connect_timeout=15&sslcert=/cockroach/cockroach-certs/client.root.crt&sslkey=/cockroach/cockroach-certs/client.root.key&sslmode=verify-full&search_path=public&sslrootcert=/cockroach/cockroach-certs/ca.crt' \    
--from-literal=DB_MIGRATOR_URL='cockroachdb://root@cockroachdb-public:26257/nimbus?application_name=alpine&connect_timeout=15&sslcert=/cockroach/cockroach-certs/client.root.crt&sslkey=/cockroach/cockroach-certs/client.root.key&sslmode=verify-full&search_path=public&sslrootcert=/cockroach/cockroach-certs/ca.crt' \    
--from-literal=OIDC_CLIENT_ID='' \    
--from-literal=OIDC_CLIENT_SECRET='' \    
--from-literal=OIDC_ISSUER_URL='' \    
--from-literal=OIDC_REDIRECT_URL='' \    
--from-literal=SSO_PROVIDER='okta' \    
--from-literal=NIMBUS_API='https://summit.usenimbus.com/graphql' \    
--from-literal=LICENSE_KEY='<license_key>' \    
--from-literal=AWS_HOSTED_ZONE_ID='<hosted_zone_id>' \    
--from-literal=AWS_VPC_IDS='{"us-west-2":"vpc-id"}' \    
--from-literal=PUBLIC_WORKSPACE='true' \    
--from-literal=HOST='<nimbus_url>' \    
--from-literal=DISABLE_TELEMETRY='true'