docs(core): documentation for github integration for private nx cloud (#22305 )

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->
Adding documentation to show how to set up a GitHub app for private nx
cloud in order to make use of the full github integration.

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

## Current Behavior
Private Nx Cloud orgs cannot use the full GitHub integration as they
need to create their own GitHub app and set the required environment
variables.
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->
Docs should support the new GitHub integration by providing the
necessary steps to set up the integration.

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #

---------

Co-authored-by: Mark Lindsey <markl@nrwl.io>

2024-05-29 10:36:24 +01:00

3.1 KiB

Raw Blame History

Custom GitHub App

Before creating your container, you'll need to create a GitHub app for your organisation.

Creating a GitHub OAuth app

From GitHub, click on your profile picture and chose "Settings":

Then "Developer settings" from the left-hand menu:

Then "GitHub Apps":

And create a new GitHub app:

Give it a name, and a homepage URL. The callback URL is the important bit. It needs to be in this form:

[your-nx-cloud-url]/callbacks/github-user

# for example
https://my.nx-enterprise.url:8080/callbacks/github-user

Once you create the app, keep a note of the Client ID and App ID:

Then generate a new client secret, and save it somewhere secure (we'll use it in a bit):

Configure Permissions for the GitHub App

The following permissions are required for Nx Cloud to work:

Repository permissions:

Contents: Read & Write
Pull requests: Read & Write
Checks: Read Only
Commit Statuses: Read & Write
Issues: Read & Write
Metadata: Read Only

Organization permissions:

Administration: Read Only
Members: Read Only

Configure Nx Cloud Installation

Using Helm:

image:
  tag: 'latest'

nxCloudAppURL: 'https://nx-cloud.myorg.com'

github:
  auth:
    enabled: true

secret:
  name: 'cloudsecret'
  githubAppClientId: 'NX_CLOUD_GITHUB_APP_CLIENT_ID'
  githubAppClientSecret: 'NX_CLOUD_GITHUB_APP_CLIENT_SECRET'
  githubAppId: 'NX_CLOUD_GITHUB_APP_APP_ID'

Note that the secret must contain NX_CLOUD_GITHUB_APP_CLIENT_ID, NX_CLOUD_GITHUB_APP_APP_ID, and NX_CLOUD_GITHUB_APP_CLIENT_SECRET ( see Nx Cloud Helm Charts for more context).

Not using Helm:

Provide the following env variables to the nx-cloud-frontend container:

NX_CLOUD_GITHUB_APP_CLIENT_ID
NX_CLOUD_GITHUB_APP_CLIENT_SECRET
NX_CLOUD_GITHUB_APP_APP_ID

{% callout title="Helm Chart Environment Variables" %} If you are using our Helm chart, you can find all the information you need about env variables in the Helm chart repository. {% /callout %}

3.1 KiB Raw Blame History