Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
External custom properties let a system you already run, such as a software catalog, own repository metadata like service ownership, criticality, lifecycle stage, or compliance status and keep GitHub’s copy current. GitHub’s September 29, 2026 changelog announced the feature, and GitHub Docs describes it as public preview as of October 7, 2026. The values are read-only inside GitHub, but they can still be used for repository views, filtering, and ruleset targeting.
Decide who should own the values first
The main decision is not technical. It is whether people should edit a repository’s business context in GitHub, or whether another system should be the single place where those values are maintained. GitHub’s changelog frames external custom properties around the second case, where the external system remains the source of truth.
| Question | Standard custom properties | External custom properties |
|---|---|---|
| Where values are maintained | In GitHub | In the external system, then pushed to GitHub |
| Can values be edited in GitHub | Yes | No, they are read-only in GitHub |
| Usable in repository views, filtering, and ruleset targeting | Yes | Yes, per GitHub’s changelog |
| Returned by the repository-values endpoint | Yes | Yes, returned with traditional property values, per GitHub Docs |
| Returned by custom-property schema endpoints | Not stated | No, per GitHub Docs |
| Counts toward the 100-definition limit per organization | Yes, combined with external definitions | Yes, combined with standard definitions |
Choose standard custom properties when the people who own a repository should update its values directly. Choose external properties when a catalog or internal portal already holds those values and should keep pushing changes.
How the integration is built
External custom properties are not switched on with a single setting. GitHub’s setup guide, titled “Integrating custom properties with an external system” in GitHub Docs, describes a GitHub App plus automation that you build or configure. The app registers a display name, and the automation writes values for each repository.
#1 Best Overall
The display name and its prefix
The app is registered with a display name that prefixes every property it creates. GitHub’s example is port.environment. The rules are strict:
- The name must be 1 to 15 alphanumeric characters.
- It is scoped to the app installation and can be registered only once for that installation.
- It cannot be changed later, so choose it deliberately before the first sync.
Permissions
GitHub documents an organization-level permission named External custom properties for repositories. Which access level you grant depends on who registers the display name.
| Who registers the display name | Access needed | Notes |
|---|---|---|
| The app itself, using its installation token | Admin | Required when the app registers its own name. |
| An organization administrator | Read and write | Suitable when an administrator registers the name. |
| Any path that writes values | Read-only is not sufficient | Read-only access cannot perform the write task. |
Automation and triggers
The automation can run on a schedule, react to GitHub webhooks, or respond to changes in the external system. Webhooks are useful in two places: a first sync when the app is installed, and populating metadata when a repository is created. A scheduled job is the simplest option when the source system does not emit events.
Setup sequence
- Choose the external system that will own the values, and list which properties it will supply.
- Register a GitHub App and choose its display name, keeping in mind the 1 to 15 alphanumeric character limit and the fact that the name cannot later be changed.
- Grant the organization permission External custom properties for repositories at the access level that matches who will register the name.
- Install the app on the organization.
- In your automation, obtain an installation access token for the app.
- Have the automation register the display name for the installation if it is not already registered.
- Create or update property values for each repository through the external-property API endpoints.
- Validate the synced values in organization or repository settings. GitHub’s guide recommends this check before relying on the data.
- Keep the app installed and the automation running. Removing either stops synchronization.
Port and self-built integrations
GitHub names Port as its first integration partner. Port’s own announcement describes using its context catalog to sync properties such as ownership and criticality into GitHub, and it describes open-beta availability. Treat those statements as Port’s claims rather than GitHub’s.
The feature is not limited to partners. GitHub’s changelog states: “You aren’t limited to partner integrations.” Its setup guide names software catalogs and internal developer portals as possible sources and says GitHub plans to add more providers. An engineering team that already maintains an internal system of record can therefore build its own GitHub App and automation instead of waiting for a named partner.
Limits, removal, and common failure points
- Definition limit: Each organization can have up to 100 custom-property definitions. Standard and external definitions count together. This figure comes from GitHub Docs, which does not state a publication date on that page; it was accessed October 7, 2026.
- Uninstalling the app: This deregisters the installation and its display name, and it removes the external properties the app created. Plan uninstalls as data-removal events, not just housekeeping.
- Read-only tokens: If automation runs with read-only access, it can read but cannot write values, so syncs appear to succeed without changing anything. Check the permission level before you debug the payload.
- Schema lookups: If a script queries custom-property schema endpoints to find external properties, it will not see them. Use the repository-values endpoint instead, which returns external properties alongside traditional values.
- Stale values: Synchronization depends on the app staying installed and the automation running. If either stops, GitHub keeps the last values written, which may no longer match the source system.
Preview status and what to verify before rollout
GitHub Docs states: “External custom properties are in public preview and subject to change.” Because the API and setup details may change, confirm the current permission names, endpoint behavior, and partner availability in GitHub Docs and the changelog before building production automation.
In practice, that means starting with a single non-critical property set, checking how the values appear in repository views and rulesets, and only then extending the sync to every repository in the organization.
The question of whether GitHub should own a value or a system of record should own it is settled by the first section above: external properties suit values maintained elsewhere, and standard properties suit values people manage in GitHub.
Best Value
Use external custom properties when a catalog or internal system already maintains repository context and you can run a GitHub App and automation to keep it current. Use standard custom properties when the values should be edited by people working in GitHub. Either way, budget for the 100-definition ceiling, the permanence of the display name, and the removal behavior when the app is uninstalled.
As a final check, confirm that your rulesets and dashboards depend on the property names you have chosen, since those names are fixed once the display name is registered.
Sources: GitHub Changelog, “Bring business context with external custom properties,” September 29, 2026. GitHub Docs, “Integrating custom properties with an external system.” Port, “GitHub External Custom Properties: Sync Business Context,” original date September 22, 2026, with later updates.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
