GitHub Repos: External Custom Properties

Yes, you can bring business context to GitHub repositories using external custom properties, and this guide explains exactly how to do it. You attach custom properties to repositories via the GitHub API or UI, then manage the values in an external system (like a CMDB or internal developer portal) and sync them back. This gives you a single source of truth for metadata like cost center, compliance level, or owning team, without locking that data inside GitHub.

What Are GitHub Custom Properties?

GitHub custom properties are key-value pairs that you can attach to repositories in an organization. They were introduced in 2023 (in public beta) and became generally available for GitHub Enterprise and Team plans. Each property has a name (e.g., cost_center) and a value (e.g., finance-123). You can define properties at the organization level, set allowed values (like a dropdown), and then assign them to individual repositories.

These properties are visible in the repository sidebar and can be used in GitHub’s search, API, and automation. For example, you can search for all repos where compliance_level equals HIPAA. This is a native way to add context without writing anything to the README or relying on folder naming conventions.

Why External Custom Properties?

Many organizations already have a system of record for business data—a CMDB, an asset management tool, or an internal developer portal like Backstage. Duplicating that data into GitHub creates drift: someone updates the cost center in the CMDB but forgets to update GitHub. External custom properties solve this by making GitHub a consumer of that data, not the source.

You might also need to compute properties dynamically. For example, you want to show the number of open security alerts as a property, or the last time a repo was deployed. GitHub’s native custom properties are static—they don’t change unless someone edits them. An external system can compute and push updates on a schedule.

How to Set Up External Custom Properties

The process involves three steps: define the properties in GitHub, create an external mapping, and sync the values.

1. Define properties in GitHub: In your organization settings, go to “Custom properties” and create each property. Choose a name, a display name, and whether it’s required. You can set allowed values (like a list of teams) or leave it free-form.
2. Build an external mapping: In your external system, maintain a table that maps repository names (or IDs) to property values. For example, a spreadsheet or database with columns: repo_name, cost_center, compliance_level.
3. Sync values via API: Use the GitHub REST API endpoint PATCH /repos/{owner}/{repo}/properties/values to update a repo’s custom properties. You can write a script (e.g., a GitHub Action or a cron job) that reads your external mapping and pushes the values to GitHub.

You can also use GitHub’s GraphQL API for the same purpose. The key is that your external system remains the authoritative source, and GitHub is updated to match.

Practical Use Cases

Here are real scenarios where external custom properties add value:

• Cost allocation: Attach a cost center or budget code to each repo, synced from your finance tool. Then you can generate reports on cloud spend per repo by combining GitHub data with your billing data.
• Compliance tracking: Mark repos as containing PII, or subject to SOC2, and sync from your compliance database. Automated checks can block changes to repos that lack the required property.
• Team ownership: If your org chart lives in Workday or a directory, you can sync the owning team for each repo, even if the team name changes.
• Lifecycle status: Set a property like status to active, archived, or deprecated, updated by your internal tool when a project is retired.

Common Problems and Misconceptions

One frequent misconception is that custom properties are only for display. In reality, they can be used in GitHub Actions, code scanning, and branch protection rules. For example, you can require a specific property value before allowing a merge.

Another issue is that GitHub’s UI only lets you edit properties manually on each repo. That’s fine for small orgs, but for hundreds of repos you need automation. Also, the API requires the property to already exist in the organization; you cannot create a property via the repo-level endpoint.

Watch out for permission requirements: only organization owners and users with the “custom properties” permission can define properties. Syncing via a service account requires that account to have write access to the repos, which can be a security concern. Use a dedicated bot account with minimal permissions.

Comparing Native vs. External Approaches

GitHub’s native custom properties are simple and free (included in your plan). They work well for static metadata that doesn’t change often. However, they lack versioning, audit trails, and the ability to compute values. For example, you cannot set a property to “the number of open issues” without an external script.

External custom properties give you flexibility and a single source of truth, but add complexity. You need to maintain the sync script, handle errors, and ensure the external system is always available. Some teams use a hybrid approach: keep critical properties (like security classification) in GitHub, and less critical ones (like marketing campaign) in an external tool.

Costs and Security Considerations

Custom properties are available on GitHub Team and Enterprise plans at no extra cost. However, the external system you use (e.g., a database or SaaS tool) may have its own costs. There’s also the engineering time to build and maintain the sync.

Security-wise, custom properties are visible to anyone with read access to the repo, so avoid storing secrets or sensitive personal data. If you need to store something like a cost center, that’s fine, but never put API keys or passwords in a property. Also, be aware that the GitHub API returns all properties to any authenticated user who can read the repo, so treat them as public metadata.

For audit purposes, GitHub logs changes to custom properties in the audit log, so you can see who changed what and when. That’s useful for compliance.

Alternatives to External Custom Properties

If you don’t want to build a custom sync, consider these alternatives:

• Repository topics: Simple, but only one-word tags, no values.
• CODEOWNERS file: Good for team ownership, but not arbitrary metadata.
• Backstage or similar developer portals: These tools can ingest GitHub data and show business context, but they don’t push back to GitHub.
• GitHub Actions to generate a metadata file: You can have a workflow that writes a metadata.json file in the repo, but that’s less structured than custom properties.

Frequently Asked Questions

Can I use custom properties in GitHub Actions? Yes, you can read them via the API inside a workflow, but there’s no direct context variable. You’d need to make an API call to fetch the property values.

Do custom properties work with GitHub Enterprise Server? Yes, they are available in GHES 3.10 and later, but the API endpoints may differ slightly. Check your version’s documentation.

How do I prevent users from changing a property? You can’t set per-property read-only in the UI, but you can use branch protection or automation to revert changes. Alternatively, only give edit permission to a bot account.

Can I have multiple values for one property? No, each property has a single value. If you need multiple values, use a JSON string or a list property (which is not natively supported).

What happens if I delete a property? The property is removed from all repos, and the values are lost. There’s no undo, so export your data first.

Is there a limit to the number of custom properties? GitHub doesn’t document a hard limit, but performance may degrade with hundreds of properties. Stick to a reasonable number (under 50) for clarity.

Related

• Compare Phone Specs: iPhone 15 vs Galaxy S24
• F1 25 Wheel & Controller Settings for Smoother Handling
• How to Block iCloud Web Access