52d04d9864
<!-- 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>
107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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](https://github.com/nrwl/nx-cloud-helm) 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](https://github.com/nrwl/nx-cloud-helm/blob/main/AUTH-GUIDE.md).
|
|
{% /callout %}
|
|
|
|
<!-- ## GitHub Enterprise
|
|
|
|
If you are running a self-hosted version of GitHub (Enterprise Server), you will need to configure one additional
|
|
environment variable:
|
|
|
|
`GITHUB_API_URL=https://custom-github-instance.com`
|
|
|
|
This will point all auth endpoints to your GitHub server (rather the public one).
|
|
|
|
{% callout type="check" title="Good to know!" %}
|
|
The above environment variable, also helps with setting up the GitHub app integration, so you can have Nx Cloud build
|
|
stats directly on your pull request. See full set up instructions [here](/ci/recipes/source-control-integration/github).
|
|
{% /callout %} -->
|