Integrate multiple GitHub Enterprise Server organizations

Give each organization in a GitHub Enterprise Server instance its own Endor Labs namespace. Projects, findings, and access control stay separate, and every organization shares one registered app. When you have too many organizations to onboard one at a time, create the installations with the Endor Labs API. An organization’s projects and findings live in the namespace that holds its installation. The integration uses the following objects:

App: You register one app for the GitHub Enterprise Server instance in your root namespace. Endor Labs always propagates the app to child namespaces, so every namespace can install it. The app is only a credential and holds no projects or findings.
Installation: You create one installation for each GitHub organization. The installation lives in the namespace you create it in and records the organization name, the GitHub installation ID, and the scanners you enable.
Project: Endor Labs creates a project for every repository in the organization, in the same namespace as the installation. Scans, findings, and SBOMs attach to the project, so they stay in that namespace too.

For an instance at https://github.example.com with a root namespace of acme, each organization maps to a namespace named after it. The prodsec organization maps to acme.prodsec, which holds the installation and a project for every prodsec repository. The app stays in acme and serves every child namespace. You can set policies, scan profiles, and notification settings once in acme and propagate them down, or set them per organization.

Create only one installation for each GitHub organization. Endor Labs scopes installations per namespace, so it accepts a second installation for the same organization in another namespace. Both installations then reconcile the same repositories, which duplicates projects, scans, and findings.

Before you begin

Ensure that the following prerequisites are complete:

An Endor Outpost deployment, or firewall rules that let Endor Labs reach your GitHub Enterprise Server instance. See Deploy Endor Labs GitHub Enterprise Server App to set this up.
A GitHub App created in your GitHub Enterprise Server instance and registered in your Endor Labs root namespace.
Owner permissions on every GitHub organization you plan to onboard.
The app registered with Any account under Where can this GitHub App be installed?. An app restricted to a single account can’t be installed in your other organizations. See Deploy Endor Labs GitHub Enterprise Server App to check this setting.
Administrative access in Endor Labs to create namespaces, installations, and authorization policies.
An API key, if you plan to create installations with endorctl or the REST API. See API keys to create one.
The jq command, if you plan to run the script in Onboard from a list of organizations.

Create a namespace for each organization

Create one child namespace for every GitHub organization before you onboard it. Endor Labs generates the fully qualified name from the parent namespace and the name you supply, so a namespace named prodsec under acme becomes acme.prodsec. See Namespaces to create namespaces one at a time in the Endor Labs user interface. To create them with the API, run the following command for each organization. See Onboard from a list of organizations to create them from a file.

endorctl api create -r Namespace \
  --namespace acme \
  --data '{"meta":{"name":"prodsec"}}'

Name each namespace after the GitHub organization it represents, in lowercase. Namespace names accept only lowercase letters, numbers, hyphens, and underscores, so the ProdSec organization maps to the prodsec namespace. Matching names keep the mapping obvious and let you build both the namespace and the installation from the same list of organizations.

Install the app in each GitHub organization

Install the app in GitHub Enterprise Server once for each organization, and record the installation ID that GitHub assigns.

In GitHub Enterprise Server, navigate to the organization that owns the app and select Settings > Developer settings > GitHub Apps.
Select the app you created for Endor Labs.
In GitHub Enterprise Server, go to Install App.
Next to the organization you want to onboard, click Install.
Choose whether Endor Labs scans all repositories or a selected subset.
Review the permissions and click Install and Authorize.
In the organization’s Application settings, click Configure next to the app.
Copy the installation ID from the end of the browser URL. In the following example, 12345678 is the installation ID and prodsec is the organization name.
https://github.example.com/organizations/prodsec/settings/installations/12345678
Record the organization name with its installation ID.
Repeat these steps for every organization.

Unlike the GitHub App for cloud, this flow has no redirect back to Endor Labs. You collect the installation ID yourself and supply it in the next step.

Add the installation to the organization namespace

Add the installation in the namespace that represents the organization. The app is visible in that namespace because Endor Labs propagates it from the root namespace.

Switch to the child namespace, such as acme.prodsec.
Select User menu > Integrations from the left sidebar.
Click Manage next to GitHub Enterprise Server under Source Control Managers.
Click Install App next to the app.
In Name of the organization, enter the GitHub organization name.
In GitHub App Installation ID, enter the installation ID you collected.
On the Scanners tab, select the scanners to enable for this organization.
Optional: On Pull Request Scans, set your pull request scanning preferences.
Click Create.

Endor Labs creates a project in this namespace for every repository the app can reach in the organization.

Create installations in bulk

Use the Endor Labs API when the number of organizations makes the Endor Labs user interface impractical. The GitHub Enterprise Server flow accepts installations directly from an API call, so you can script the whole onboarding. First, get the UUID of the registered app from your root namespace.

endorctl api list -r SCMApp \
  --namespace acme \
  --field-mask "uuid,spec.github_app.app_name,spec.api_base_url"

Then create one installation for each organization in that organization’s namespace.

endorctl api create -r Installation \
  --namespace acme.prodsec \
  --data '{
    "spec": {
      "platform_type": "PLATFORM_SOURCE_GITHUB_ENTERPRISE",
      "scm_app_uuid": "<scm-app-uuid>",
      "login": "prodsec",
      "external_id": "12345678",
      "enabled_features": ["ENABLED_FEATURE_TYPE_GIT_SCAN", "ENABLED_FEATURE_TYPE_SECRETS_SCAN"],
      "github_config": {
        "enable_pr_scans": true,
        "enable_pr_comments": true
      }
    }
  }'

Endor Labs resolves the app, the host URL, and the installation name from the app UUID, so you don’t supply them. Creating an installation again for the same organization in the same namespace replaces its settings with the ones in the request, including scanners and pull request settings.

Installation fields

The following fields control a GitHub Enterprise Server installation.

Onboard from a list of organizations

Keep an organizations.csv file with one organization name and its installation ID on each line. Enter each organization name exactly as GitHub shows it, including capital letters. The file has no header row.

prodsec,12345678
payments,23456789
platform,34567890

The following script creates the namespace and the installation for every row. It skips any line that doesn’t hold an organization name and a numeric installation ID, so blank lines and malformed rows don’t reach the API.

#!/usr/bin/env bash
set -euo pipefail

PARENT_NS="acme"
APP_UUID="<scm-app-uuid>"
FEATURES='["ENABLED_FEATURE_TYPE_GIT_SCAN"]'

command -v jq >/dev/null || { echo "This script needs jq." >&2; exit 1; }

while IFS=, read -r org installation_id || [[ -n "$org" ]]; do
  org="${org//[[:space:]]/}"
  installation_id="${installation_id//[[:space:]]/}"

  if [[ -z "$org" ]] || [[ ! "$installation_id" =~ ^[0-9]+$ ]]; then
    echo "Skipping line: $org,$installation_id" >&2
    continue
  fi

  # Namespace names must be lowercase. Keep the organization name as-is for login.
  ns_name="$(printf '%s' "$org" | tr '[:upper:]' '[:lower:]')"
  echo "Onboarding $org into $PARENT_NS.$ns_name" >&2

  if ! endorctl api get -r Namespace --namespace "$PARENT_NS" --name "$ns_name" >/dev/null 2>&1; then
    endorctl api create -r Namespace \
      --namespace "$PARENT_NS" \
      --data "$(jq -n --arg name "$ns_name" '{meta: {name: $name}}')"
  fi

  # Creating an existing installation again replaces its settings, so skip it.
  if endorctl api list -r Installation \
      --namespace "$PARENT_NS.$ns_name" \
      --filter "spec.login==$org" \
      --field-mask uuid 2>/dev/null | grep -q '"uuid"'; then
    echo "Installation for $org already exists, skipping." >&2
    continue
  fi

  endorctl api create -r Installation \
    --namespace "$PARENT_NS.$ns_name" \
    --data "$(jq -n \
      --arg app "$APP_UUID" \
      --arg login "$org" \
      --arg id "$installation_id" \
      --argjson features "$FEATURES" \
      '{spec: {
          platform_type: "PLATFORM_SOURCE_GITHUB_ENTERPRISE",
          scm_app_uuid: $app,
          login: $login,
          external_id: $id,
          enabled_features: $features
        }}')"
done < organizations.csv

The || [[ -n "$org" ]] condition processes the last line even when the file has no trailing newline. If a create call fails, the script stops at that organization. Fix the row and run the script again. It skips organizations that already have an installation.

Control access for each namespace

Grant access per namespace with authorization policies. A policy names its target namespaces and can include their children, so each team sees only its own organizations while sharing one app.

Give platform administrators a policy on acme that propagates to children, so they see every organization.
Give each team a policy on its own namespace, such as acme.prodsec.
Give someone who works across two organizations a policy on each namespace.

See Authorization policies to create and scope a policy.

Verify the namespace mapping

List every GitHub Enterprise Server installation across your namespace tree and confirm that each organization is in the namespace you expect.

endorctl api list -r Installation \
  --namespace acme \
  --traverse \
  --filter "spec.platform_type==PLATFORM_SOURCE_GITHUB_ENTERPRISE" \
  --field-mask "tenant_meta.namespace,spec.login,spec.external_id"

Check the output for an organization that appears under more than one namespace. Delete the installation you don’t want, along with the projects it created. To confirm that each project is in the right namespace, list the projects in one child namespace.

endorctl api list -r Project \
  --namespace acme.prodsec \
  --field-mask "meta.name,spec.git.full_name"

Known limitations

Keep the following constraints in mind when you plan the mapping:

You can register only one app for each GitHub Enterprise Server instance in a tenant, and only in the root namespace.
Decide which namespace owns each organization before you onboard. Installations are unique per namespace, so Endor Labs accepts a second installation for the same organization in another namespace and reconciles the organization twice.
The organization name and the installation ID are fixed after creation. To change either one, delete the installation and create a new one.
Moving an organization to a different namespace means deleting the installation and its projects, then creating the installation in the new namespace.
The GitHub Enterprise Server App has the same limitations as the GitHub App for cloud. See Limitations to review them.

Next steps

Manage GitHub Enterprise Server App on Endor Labs to update scanners or remove an installation.
Configure a scan profile to control how Endor Labs scans each namespace.
Namespaces to review the namespace tree you created.

Introduction

Setup & Deployment

Inventory & Insights

Scan with Endor Labs

Risk Remediation

Integrations

Secure AI Coding

Platform Administration

Best Practices

Threat Center

Trust & Compliance

Integrate multiple GitHub Enterprise Server organizations

Before you begin

Create a namespace for each organization

Install the app in each GitHub organization

Add the installation to the organization namespace

Create installations in bulk

Installation fields

Onboard from a list of organizations

Control access for each namespace

Verify the namespace mapping

Known limitations

Next steps

​Before you begin

​Create a namespace for each organization

​Install the app in each GitHub organization

​Add the installation to the organization namespace

​Create installations in bulk

​Installation fields

​Onboard from a list of organizations

​Control access for each namespace

​Verify the namespace mapping

​Known limitations

​Next steps

Before you begin

Create a namespace for each organization

Install the app in each GitHub organization

Add the installation to the organization namespace

Create installations in bulk

Installation fields

Onboard from a list of organizations

Control access for each namespace

Verify the namespace mapping

Known limitations

Next steps