The Problem with Unstructured Repositories

If you’re managing a lot of repositories in an organization, you’ve probably run into this problem: finding what you need gets harder as the number of repos grows. You might have infrastructure-as-code repos mixed with documentation, testing projects alongside applications, and proof-of-concept work scattered everywhere.

The fact that organizations are not really built to structure repositories does not help with the problem, but something that does help is Custom Properties!

Custom Properties to the Rescue

GitHub’s custom properties feature lets you add structured metadata to repositories (as the docs so nicely put it). It’s a relatively new feature that makes organizing and searching repositories much easier.

I recently implemented a “project-type” custom property across our organization, and it’s been a game-changer for how we structure and find repositories.

Setting Up the Project-Type Property

Here’s how I set it up:

1. Navigate to Organization Settings

   • Go to your organization → Settings → Custom properties

2. Create a New Property

   • Select “New property”
   • Name it project-type

3. Configure the Property

   • Type: Single select (this means each repository can only have one project type)
   • Default value: undefined (for repositories that haven’t been categorized yet)
   • Required: Yes (this ensures all repositories get categorized)

4. Add the Options I added these project types:

   • infrastructure-as-code
   • testing
   • application
   • documentation
   • proof-of-concept

Why These Settings?

Single select makes sense because a repository typically has one primary purpose. You might have a repo that contains both code and documentation, but it’s usually one or the other that’s the main focus.

Default value of “undefined” helps identify repositories that haven’t been categorized yet. It’s better than leaving them empty because you can search for props.project-type:undefined to find repos that need attention.

Required on all repositories ensures consistency. When someone creates a new repository, they have to pick a project type right away. This prevents the accumulation of uncategorized repos.

Using Custom Properties for Search

The real power comes when you use these properties for searching. GitHub’s repository search supports custom properties with a simple syntax.

Press / in the repository search bar (or use the hotkey), then type:

props.project-type:application

This instantly filters to show only repositories tagged as “application” type.

You can combine this with other search terms too:

props.project-type:infrastructure-as-code language:terraform

This finds all infrastructure-as-code repositories that use Terraform.

Using the API

One can leverage the gh-cli to easily filter repositories in automation

gh api --method GET "orgs/ur_org/properties/values" --jq '.[] |
 select(.properties[] | select (.property_name == "project-type" and .value == "documentation")) | .repository_name'

This example grabs the documentation project-type repositories and outputs the repository_name property. As an example.

Closing Thoughts

Custom properties are a simple feature, but they solve a real problem. If you’re managing multiple repositories and finding it hard to keep track of them, give custom properties a try. Start with one property that addresses your biggest organizational challenge, and expand from there.

The project-type property has made our repository management much more efficient, and I’m sure there are other custom properties we’ll add as we identify more organizational needs.