GitHub repositories usually contain technical information such as source code, workflows, issues, pull requests, releases, and dependency configuration.
As an organization grows, another problem appears: technical metadata does not always tell you how a repository is used by the business.
For example, an organization may have hundreds of repositories representing:
Customer Portal
Payment API
Inventory Service
Internal Admin Tool
Mobile Application
AI Assistant
Data Pipeline
GitHub can manage the source code for all of them, but engineering teams may also need information such as:
Which business unit owns the repository?
Which team maintains it?
Is it production or development?
Which application does it belong to?
What environment does it support?
How critical is the application?
Which technology stack does it use?
GitHub custom repository properties provide a way to attach structured metadata to repositories.
That metadata can then become useful in repository management, automation, search, reporting, and GitHub Actions workflows.
What Are GitHub Custom Properties?
A custom property is structured metadata associated with a repository.
Instead of storing information only in documentation:
README.md
Owner: Platform Team
Environment: Production
Business Unit: Commerce
you can represent it as repository metadata:
Owner = Platform
Environment = Production
BusinessUnit = Commerce
This creates machine-readable information that automation can consume.
The important difference is that custom properties are metadata about the repository rather than application code inside the repository.
Why Business Context Matters
Consider an organization with 500 repositories.
A security team may want to identify:
All production repositories
owned by the Commerce organization
that process customer data
If that information exists only in README files, automated reporting becomes difficult.
With structured repository properties, the information can be queried and used by organizational workflows.
A repository might have:
BusinessUnit = Commerce
Environment = Production
OwnerTeam = Payments
Criticality = High
Now automation can make decisions based on those values.
Repository Properties vs Repository Topics
GitHub provides several ways to describe repositories.
Repository topics are useful for classification:
dotnet
azure
microservices
ai
Custom properties are more appropriate for structured organizational metadata:
Environment = Production
OwnerTeam = Payments
Lifecycle = Active
The distinction is useful:
Metadata Type | Typical Purpose |
|---|---|
Repository name | Identity |
Description | Human-readable summary |
Topics | Discoverability and classification |
Custom properties | Structured organizational metadata |
Files | Application-specific configuration |
Custom properties are particularly useful when organizations need consistent values across many repositories.
Designing a Property Model
Before creating properties, define what information is actually useful.
For example:
OwnerTeam
BusinessUnit
Environment
ApplicationType
Lifecycle
Criticality
A repository might then look like:
Repository:
payment-api
OwnerTeam:
Payments
BusinessUnit:
Commerce
Environment:
Production
ApplicationType:
API
Criticality:
High
Avoid creating properties simply because the platform allows them.
Each property should answer a real operational or business question.
Property Values Should Be Consistent
One of the biggest advantages of structured metadata is consistency.
Consider these values:
Production
Prod
production
PROD
Live
They may all mean the same thing to humans, but automation sees different strings.
Prefer controlled values:
Development
Staging
Production
Then workflows can reliably test:
Environment == "Production"
This becomes especially important when properties are used by organization-wide automation.
Using Repository Properties in GitHub Actions
The value of repository metadata increases when workflows can use it.
A workflow may need to behave differently depending on the repository's business context.
For example:
Production repository
|
v
Extended security checks
Development repository
|
v
Standard validation
The workflow can obtain repository metadata through GitHub APIs or related automation mechanisms and use it as input to subsequent steps.
A conceptual workflow might look like:
jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Read repository metadata
run: |
echo "Loading repository properties"
- name: Run validation
run: |
echo "Running repository-specific checks"
The exact API call depends on how the organization exposes and manages repository properties.
Using the GitHub API
Repository metadata can be retrieved programmatically through GitHub's APIs.
A .NET service could encapsulate that operation.
For example:
public sealed class RepositoryMetadata
{
public string OwnerTeam { get; init; } = string.Empty;
public string Environment { get; init; } = string.Empty;
public string BusinessUnit { get; init; } = string.Empty;
}
Then define a service:
public interface IRepositoryMetadataService
{
Task<RepositoryMetadata> GetAsync(
string owner,
string repository,
CancellationToken cancellationToken = default);
}
The service can call the appropriate GitHub API endpoint and map the response into an application-specific model.
The important design principle is to keep GitHub API details out of the rest of the application.
Business Rules Based on Repository Metadata
Custom properties become particularly useful when they drive organizational rules.
For example:
Criticality = High
|
v
Additional security checks
Another repository:
Environment = Development
|
v
Standard CI
And:
ApplicationType = Library
|
v
Package validation
This allows a common workflow framework to support many repositories without copying large amounts of configuration.
A Metadata-Driven Workflow
Consider an organization with three repository types:
API
Web Application
Library
A central workflow could inspect repository metadata:
Repository
|
v
Read ApplicationType
|
+---- API ---------> API Tests
|
+---- Web ---------> Browser Tests
|
+---- Library -----> Package Tests
This is more scalable than maintaining a completely different workflow for every repository.
Production vs Non-Production
Environment metadata can also be useful.
For example:
Environment = Production
could trigger additional controls:
Production
|
+---- Security Scan
+---- Compliance Check
+---- Deployment Approval
+---- Extended Tests
While:
Environment = Development
may require only:
Build
Test
Lint
The actual policy should be defined by the organization's engineering and security requirements.
Custom Properties and Centralized Workflows
Large organizations often want to standardize CI/CD without forcing every repository to maintain completely independent workflow logic.
A centralized approach can use repository properties as configuration.
For example:
Join the conversation! Your thoughts help the community grow.