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>

docs/generated/manifests/ci.json

@@ -709,6 +709,17 @@
                 "isExternal": false,
                 "path": "/ci/recipes/enterprise/on-premise/advanced-config",
                 "tags": []
+              },
+              {
+                "id": "custom-github-app",
+                "name": "Custom GitHub App",
+                "description": "",
+                "mediaImage": "",
+                "file": "nx-cloud/enterprise/on-premise/custom-github-app",
+                "itemList": [],
+                "isExternal": false,
+                "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+                "tags": []
               }
             ],
             "isExternal": false,
@@ -1282,6 +1293,17 @@
             "isExternal": false,
             "path": "/ci/recipes/enterprise/on-premise/advanced-config",
             "tags": []
+          },
+          {
+            "id": "custom-github-app",
+            "name": "Custom GitHub App",
+            "description": "",
+            "mediaImage": "",
+            "file": "nx-cloud/enterprise/on-premise/custom-github-app",
+            "itemList": [],
+            "isExternal": false,
+            "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+            "tags": []
           }
         ],
         "isExternal": false,
@@ -1465,6 +1487,17 @@
         "isExternal": false,
         "path": "/ci/recipes/enterprise/on-premise/advanced-config",
         "tags": []
+      },
+      {
+        "id": "custom-github-app",
+        "name": "Custom GitHub App",
+        "description": "",
+        "mediaImage": "",
+        "file": "nx-cloud/enterprise/on-premise/custom-github-app",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+        "tags": []
       }
     ],
     "isExternal": false,
@@ -1559,6 +1592,17 @@
     "path": "/ci/recipes/enterprise/on-premise/advanced-config",
     "tags": []
   },
+  "/ci/recipes/enterprise/on-premise/custom-github-app": {
+    "id": "custom-github-app",
+    "name": "Custom GitHub App",
+    "description": "",
+    "mediaImage": "",
+    "file": "nx-cloud/enterprise/on-premise/custom-github-app",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+    "tags": []
+  },
   "/ci/recipes/enterprise/dte": {
     "id": "dte",
     "name": "Custom Distributed Task Execution",

docs/generated/manifests/menus.json

@@ -5628,6 +5628,14 @@
                     "isExternal": false,
                     "children": [],
                     "disableCollapsible": false
+                  },
+                  {
+                    "name": "Custom GitHub App",
+                    "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+                    "id": "custom-github-app",
+                    "isExternal": false,
+                    "children": [],
+                    "disableCollapsible": false
                   }
                 ],
                 "disableCollapsible": false
@@ -6046,6 +6054,14 @@
                 "isExternal": false,
                 "children": [],
                 "disableCollapsible": false
+              },
+              {
+                "name": "Custom GitHub App",
+                "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+                "id": "custom-github-app",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
               }
             ],
             "disableCollapsible": false
@@ -6179,6 +6195,14 @@
             "isExternal": false,
             "children": [],
             "disableCollapsible": false
+          },
+          {
+            "name": "Custom GitHub App",
+            "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+            "id": "custom-github-app",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
           }
         ],
         "disableCollapsible": false
@@ -6247,6 +6271,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Custom GitHub App",
+        "path": "/ci/recipes/enterprise/on-premise/custom-github-app",
+        "id": "custom-github-app",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Custom Distributed Task Execution",
         "path": "/ci/recipes/enterprise/dte",

docs/map.json

@@ -1807,6 +1807,11 @@
                       "name": "Advanced Configuration",
                       "id": "advanced-config",
                       "file": "nx-cloud/enterprise/on-premise/advanced-config"
+                    },
+                    {
+                      "name": "Custom GitHub App",
+                      "id": "custom-github-app",
+                      "file": "nx-cloud/enterprise/on-premise/custom-github-app"
                     }
                   ]
                 },

docs/nx-cloud/enterprise/on-premise/custom-github-app.md

@@ -0,0 +1,106 @@
+# 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":
+
+![Step 1](/nx-cloud/enterprise/on-premise/images/github_auth_step_1.png)
+
+Then "Developer settings" from the left-hand menu:
+
+![Step 2](/nx-cloud/enterprise/on-premise/images/github_auth_step_2.png)
+
+Then "GitHub Apps":
+
+![Step 3](/nx-cloud/enterprise/on-premise/images/github_custom_app_step_3.avif)
+
+And create a new GitHub app:
+
+![Step 4](/nx-cloud/enterprise/on-premise/images/github_custom_app_step_5.avif)
+
+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:
+
+![Step 6](/nx-cloud/enterprise/on-premise/images/github_custom_app_step_6.avif)
+
+Then generate a new client secret, and save it somewhere secure (we'll use it in a bit):
+
+![Step 7](/nx-cloud/enterprise/on-premise/images/github_auth_step_7.png)
+
+## 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 %} -->

docs/shared/reference/sitemap.md

@@ -287,6 +287,7 @@
         - [Authenticate via SAML](/ci/recipes/enterprise/on-premise/auth-saml)
         - [Authenticate via SAML on Managed Version](/ci/recipes/enterprise/on-premise/auth-saml-managed)
         - [Advanced Configuration](/ci/recipes/enterprise/on-premise/advanced-config)
+        - [Custom GitHub App](/ci/recipes/enterprise/on-premise/custom-github-app)
       - [Custom Distributed Task Execution](/ci/recipes/enterprise/dte)
         - [GitHub Actions Custom DTE](/ci/recipes/enterprise/dte/github-dte)
         - [Circle CI Custom DTE](/ci/recipes/enterprise/dte/circle-ci-dte)