Add more information about GHES broker and a notion of subdomain isol…

…ation. (#1447)
RoadieHQ · Dec 6, 2024 · 4fe11bb · 4fe11bb
1 parent 432477c
commit 4fe11bb
Showing 1 changed file with 78 additions and 0 deletions.
diff --git a/content/docs/integrations/ghe/index.md b/content/docs/integrations/ghe/index.md
@@ -62,13 +62,91 @@ Roadie supports GitHub Enterprise Servers via both public access via the Interne
    * The URL should have a value like `https://<your-roadie-tenant>.mydomain.dev`
 2. Enable the broker connection and configured your broker connection path. 
    * The path should have a value like `broker://my-ghes-broker-token` 
+3. (Optionally, not recommended) disable subdomain isolation configuration for raw URLs
+   * If you have not enabled subdomain isolation on your GHES instance, you can check the configuration flag to allow path based URLs to be used when retrieving raw files. Note that you need to manually modify the Broker client `accept.json` configuration file to support this access pattern (see below).
 
 ![ghes-settings.webp](ghes-settings.webp)
 
 ### Step 6. (GHES behind broker only) Configure broker client
 1. Configure your broker client connection as defined in [the Roadie broker documentation](/docs/integrations/broker/#setup-broker-client).
    * You can find the recommended initial configurations and/or dockerfiles from the repository linked in broker documentation above.
 
+The easiest way to get started with broker configuration is to run the client locally with an `accept.json` configuration file that makes it easier to configure. The example files are listed below:
+
+<details><summary>Standard GHES broker file</summary>
+
+```json
+{
+   "public": [
+      {
+         "//": "Get broker connection status",
+         "method": "GET",
+         "path": "/healthcheck"
+      }
+   ],
+   "private": [
+      {
+         "method": "POST",
+         "path": "/graphql",
+         "origin": "${GHES_URL}",
+         "auth": {
+            "scheme": "token",
+            "token": "${GHES_TOKEN}"
+         }
+      },
+      {
+         "method": "GET",
+         "path": "/*",
+         "origin": "${GHES_RAW_URL}",
+         "auth": {
+            "scheme": "token",
+            "token": "${GHES_TOKEN}"
+         }
+      }
+   ]
+}
+```
+
+</details>
+
+<details><summary>GHES broker file with path based RAW URLs</summary>
+
+```json
+{
+   "public": [
+      {
+         "//": "Get broker connection status",
+         "method": "GET",
+         "path": "/healthcheck"
+      }
+   ],
+   "private": [
+      {
+         "method": "POST",
+         "path": "/graphql",
+         "origin": "${GHES_URL}",
+         "auth": {
+            "scheme": "token",
+            "token": "${GHES_TOKEN}"
+         }
+      },
+      {
+         "method": "GET",
+         "path": "/raw/*",
+         "origin": "${GHES_URL}",
+         "auth": {
+            "scheme": "token",
+            "token": "${GHES_TOKEN}"
+         }
+      }
+   ]
+}
+```
+
+</details>
+
+
+
 ## Next Steps