logo

Github App Creation

Introduction

Nimbus built integrations with GitHub to seamlessly automate development workflow.
In this documentation, we will show you how to
  1. create a GitHub app
  1. 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

  1. 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

  1. Log in to your GitHub account. From the top right corner, select user settings
  1. Scroll all the way down. In Developer Settings, select “GitHub Apps”
  1. Create GitHub App
    1. “GitHub App name” section: input any name you’d like, for example, “Nimbus”
    2. “Homepage URL” section: put the domain where you access the Nimbus app
    3. “Callback URL” section: <nimbus_url>/oauth/github/callback
    4. Leave “Expire user authorization tokens” checked
    5. Leave “Request user authorization (OAuth) during installation” and “Enable Device Flow” unchecked
    6. “Setup URL” section: <nimbus_url>/oauth/github/callback
      1. This is the same as the “Callback URL”
    7. Leave “Redirect on update” unchecked
    8. Uncheck the “Active” checkbox in the Webhook section
    9. In the Permissions section:
      1. Repository permissions:
        1. Actions: Read + Write
        2. Content: Read-only
      2. Organization permissions:
        1. No change
      3. Account permissions:
        1. Email addresses: Read-only
    10. In the section “where can this GitHub App be installed?”
      1. Choose “Any account”
    11. 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:
Image without caption
Image without caption
  1. App ID: in the screenshot above, it’s 5. We refer to it by <github_app_id>
  1. Client ID: in the screenshot above, it’s under the App ID. We refer to it by <github_client_id>
  1. 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>”
    1. Note the <github_app_name> here, which we will use in a later section
  1. Callback URL: we refer to it by <github_oauth_redirect_url>
Now we will proceed to two more setup steps:
  1. Generate a new client's secret
    1. And save the secret string, we will refer to it by <github_client_secret> here.
      1. Image without caption
  1. Scroll all the way down, and generate a private key
    1. And remember where the pem file is downloaded, we will refer to the file path by <github_app_private_key>
      1. Image without caption
      2. 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'