adding hub-sync feature code

.env.example

@@ -15,3 +15,32 @@
 
 # Uncomment this to get GitHub comments for the Pull Request Workflow.
 # ENABLE_PR_COMMENT=true
+
+# ADMIN_REPO=safe-settings-config
+CONFIG_PATH=.github
+SETTINGS_FILE_PATH=settings.yml
+
+# URL prefix for deployment behind a proxy (appears in browser address bar)
+# Default: /safe-settings
+# Set to empty string for root path deployment: SAFE_SETTINGS_HUB_URL_PREFIX=
+# SAFE_SETTINGS_HUB_URL_PREFIX=/safe-settings
+
+# Configuration support for Hub-Sync safe-settings feature
+# SAFE_SETTINGS_HUB_REPO=safe-settings-config-master
+# SAFE_SETTINGS_HUB_ORG=foo-training
+# A subfolder under 'CONFIG_PATH' where the 'organizations/<org>/<repo>' structure is found
+# SAFE_SETTINGS_HUB_PATH=safe-settings
+# SAFE_SETTINGS_HUB_DIRECT_PUSH=true
+
+
+
+# ┌────────────── second (optional)
+# │ ┌──────────── minute
+# │ │ ┌────────── hour
+# │ │ │ ┌──────── day of month
+# │ │ │ │ ┌────── month
+# │ │ │ │ │ ┌──── day of week
+# │ │ │ │ │ │
+# │ │ │ │ │ │
+# * * * * * *
+# CRON=* * * * * # Run every minute

.gitignore

@@ -128,7 +128,7 @@ npm-debug.log
 .DS_Store
 node_modules/
 private-key.pem
-.env
+*.env
 *.pem
 .vscode
 yarn.lock
@@ -140,3 +140,6 @@ samconfig.toml
 # test file to be ignored
 test.log
 reports
+
+#all general log files
+*.log

app.yml

@@ -22,10 +22,10 @@ default_events:
   - pull_request
   - push
   - repository
+  - repository_dispatch
   - repository_ruleset
   - team
 
-
 # The set of permissions needed by the GitHub App. The format of the object uses
 # the permission name for the key (for example, issues) and the access type for
 # the value (for example, write).
@@ -114,6 +114,14 @@ default_permissions:
     # https://developer.github.com/v3/apps/permissions/
     organization_administration: write
 
+    # Manage custom organization roles.
+    # https://docs.github.com/en/enterprise-cloud@latest/rest/authentication/permissions-required-for-github-apps?apiVersion=2026-03-10#organization-permissions-for-custom-organization-roles
+    organization_custom_org_roles: write
+
+    # Manage custom repository roles.
+    # https://docs.github.com/en/enterprise-cloud@latest/rest/authentication/permissions-required-for-github-apps?apiVersion=2026-03-10#organization-permissions-for-custom-repository-roles
+    organization_custom_roles: write
+
     # Manage Actions variables.
     # https://docs.github.com/en/rest/actions/variables?apiVersion=2022-11-28
     actions_variables: write

docs/README.md

@@ -10,3 +10,5 @@
 | Configure deployment environments | [Deployment Environments](github-settings/6.%20deployment-environments.md) |
 | Configure auto-link references | [AutoLinks](github-settings/7.%20autolinks.md) |
 | Configure pre-defined labels for issues and pull requests | [Labels](github-settings/8.%20labels.md) |
+
+For information on disabling plugins, see [Disabling plugins](../README.md#disabling-plugins-disable_plugins) in the root README.

docs/github-settings/4. teams.md

@@ -38,7 +38,7 @@ teams:
 </td></tr>
 <tr><td>
 <p>&emsp;<code>permission</code><span style="color:gray;">&emsp;<i>string</i>&emsp;</span></p>
-<p>The permission to grant the team on this repository. We accept the following permissions to be set: <code>pull</code>, <code>triage</code>, <code>push</code>, <code>maintain</code>, <code>admin</code> and you can also specify a custom repository role name, if the owning organization has defined any. If no permission is specified, the team's <code>permission</code> attribute will be used to determine what permission to grant the team on this repository.</p>
+<p>The permission to grant the team on this repository. We accept the following permissions to be set: <code>pull</code>, <code>triage</code>, <code>push</code>, <code>maintain</code>, <code>admin</code> and you can also specify a custom repository role name, if the owning organization has defined any.</p>
 <p>Default: <code>push</code></p>
 </td><td style="vertical-align:top">
 
@@ -48,5 +48,18 @@ teams:
     permission: maintain
 ```
 
+</td></tr>
+<tr><td>
+<p>&emsp;<code>external_group</code><span style="color:gray;">&emsp;<i>string</i>&emsp;</span></p>
+<p>Optional. The <strong>display name</strong> of an external IdP group (as listed under your organization's external groups) to link to the team. <code>safe-settings</code> looks up the group's id by display name via <a href="https://docs.github.com/en/enterprise-cloud@latest/rest/teams/external-groups?apiVersion=2022-11-28#list-external-groups-available-to-an-organization"><code>GET /orgs/{org}/external-groups</code></a> and links the team via <a href="https://docs.github.com/en/enterprise-cloud@latest/rest/teams/external-groups?apiVersion=2022-11-28#update-the-connection-between-an-external-group-and-a-team"><code>PATCH /orgs/{org}/teams/{team_slug}/external-groups</code></a>. The link is reconciled on every sync and is idempotent (it skips the PATCH when the team is already linked to the same group). The external-groups list is fetched at most once per org per sync, only when at least one team entry uses this property. If the named group does not exist for the org, an error is logged and the team-repo association still applies.</p>
+</td><td style="vertical-align:top">
+
+```yaml
+teams:
+  - name: expert-services-developers
+    permission: push
+    external_group: "Engineering - Expert Services"
+```
+
 </td></tr>
 </table>

docs/hubSyncHandler/BASE_PATH.md

@@ -0,0 +1,141 @@
+# URL Prefix Configuration
+
+Safe Settings supports deployment behind a reverse proxy (like NGINX) that routes to the application using a custom URL prefix.
+
+## Overview
+
+By default, Safe Settings serves its UI and API from `/safe-settings`:
+- Dashboard: `http://localhost:3000/safe-settings/dashboard`
+- API: `http://localhost:3000/safe-settings/api/safe-settings/...`
+
+You can customize this by setting the `SAFE_SETTINGS_HUB_URL_PREFIX` environment variable, or set it to an empty string for root path deployment:
+- Dashboard (root): `http://localhost:3000/dashboard`
+- API (root): `http://localhost:3000/api/safe-settings/...`
+
+## Configuration
+
+### Default Behavior
+
+Safe Settings defaults to `SAFE_SETTINGS_HUB_URL_PREFIX=/safe-settings`. No configuration needed for this default.
+
+### Customizing the URL Prefix
+
+To use a different URL prefix, add to your `.env` file:
+
+```bash
+SAFE_SETTINGS_HUB_URL_PREFIX=/my-custom-path
+```
+
+### Root Path Deployment
+
+To deploy at the root path instead, set SAFE_SETTINGS_HUB_URL_PREFIX to an empty string:
+
+```bash
+SAFE_SETTINGS_HUB_URL_PREFIX=
+```
+
+**Important:** 
+- The SAFE_SETTINGS_HUB_URL_PREFIX will automatically add a leading `/` if you forget it
+- Examples: `/safe-settings`, `safe-settings`, `/apps/safe-settings`, `custom-prefix` (all work!)
+- Do NOT end with `/`
+- Set to empty string or `/` for root path deployment
+
+### 2. Rebuild the UI
+
+After changing the SAFE_SETTINGS_HUB_URL_PREFIX, you must rebuild the Next.js UI:
+
+```bash
+cd ui
+npm run build
+cd ..
+```
+
+### 3. Restart the application
+
+```bash
+npm start
+# or
+npm run dev
+```
+
+## NGINX Configuration Example
+
+Here's an example NGINX configuration for routing requests to Safe Settings at `/safe-settings`:
+
+Make sure to set `SAFE_SETTINGS_HUB_URL_PREFIX=/safe-settings` in your `.env` file before starting the application.
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Route /safe-settings to Safe Settings application
+    location /safe-settings {
+        proxy_pass http://localhost:3000/safe-settings;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Route other paths to different applications
+    location /other-app {
+        proxy_pass http://localhost:4000;
+        # ... other proxy settings
+    }
+}
+```
+
+## How It Works
+
+The SAFE_SETTINGS_HUB_URL_PREFIX configuration affects three layers:
+
+1. **Backend Routing** (`lib/routes.js`): Express router is mounted at the SAFE_SETTINGS_HUB_URL_PREFIX instead of root
+2. **Next.js Configuration** (`ui/next.config.js`): The `basePath` setting tells Next.js to generate assets with the correct URL prefix
+3. **Frontend Links & API Calls** (`ui/src/app/**`): Navigation links and API fetch calls use the `withBasePath()` utility to prepend the URL prefix
+
+All API endpoints in the frontend components (`EnvVariables.jsx`, `OrganizationsTable.jsx`, `Safe-settings-hubContent.jsx`, `HubOrgGraph.jsx`) have been updated to use `withBasePath()` for proper routing.
+
+## Testing Locally
+
+To test the default SAFE_SETTINGS_HUB_URL_PREFIX locally without NGINX:
+
+1. No configuration needed (defaults to `/safe-settings`)
+2. Build UI: `cd ui && npm run build && cd ..`
+3. Start app: `npm run dev`
+4. Access at: `http://localhost:3000/safe-settings/dashboard`
+
+To test a custom SAFE_SETTINGS_HUB_URL_PREFIX:
+
+1. Set `SAFE_SETTINGS_HUB_URL_PREFIX=/your-path` in `.env`
+2. Rebuild UI: `cd ui && npm run build && cd ..`
+3. Start app: `npm run dev`
+4. Access at: `http://localhost:3000/your-path/dashboard`
+
+## Troubleshooting
+
+### Assets not loading
+- Make sure you rebuilt the UI after changing SAFE_SETTINGS_HUB_URL_PREFIX
+- Check browser console for 404 errors
+- Verify NGINX is correctly proxying all paths under the URL prefix
+
+### API calls failing
+- Ensure your proxy passes the full path including SAFE_SETTINGS_HUB_URL_PREFIX
+- Check that relative API URLs are being used (not absolute URLs)
+
+### Navigation broken
+- Verify all `<a>` tags use `withBasePath()` utility
+- Check that `pathname` comparisons account for the URL prefix
+
+## Deploying at Root Path
+
+To deploy at root path instead of the default `/safe-settings`:
+
+1. Set `SAFE_SETTINGS_HUB_URL_PREFIX=` (empty string) in `.env`
+2. Rebuild UI: `cd ui && npm run build && cd ..`
+3. Restart application
+4. Access at: `http://localhost:3000/dashboard`