Custom Properties for Repos Overview

10/8/24

Summary

Custom properties can greatly enhance the management of repositories in GitHub by providing additional metadata and control, currently at the Organization level, and soon at the Enterprise as well. When leveraged with other features such as repo rulesets, security configurations, GitHub Actions, and the various dashboarding / search functionalities available in GitHub, custom properties can help teams better organize their projects, improve workflows, and ensure that important processes and policies are adhered to across repos.

In general, GitHub recommends minimizing the number of organizations you create. Having fewer organizations encourages greater collaboration and innersourcing, which increases efficiency. This can be a challenge for some enterprises, who, due to organizational history, acquisitions, or corporate structure, benefit from a more hierarchical management experience. Custom properties provide the means for these enterprises to achieve the best of both worlds.

This 1-pager outlines best practices for assigning and managing custom properties in GitHub repos, as well as some common use cases and properties that can help streamline collaboration within development teams.

Custom Properties: What are your options?

As detailed in the documentation, custom properties are private and can only be viewed by people with read permissions to the repo. Properties have a name, a description, and a type. The type can be a text string, a single select field, a multi select field, or a true/false boolean.

You have two additional selection options to consider:

  • Allow repository actors to set this property: When enabled, repo users and apps with the repo-level "custom properties" fine-grained permission will be able to set and update the property value for their repo.
  • Require this property for all repositories and add a default value: This means that you require that all repos in your organization have a value for this property. Repos that don’t have an explicit value for this property will inherit the default value.

You can create custom properties in the Organization’s settings, under Repos > Custom Properties, and in this same location you can filter on and assign your properties to repos. Users with proper permissions can also adjust custom properties within a repo’s settings.

Ideas of Custom Properties to consider

  • Data Categorization
    • Compliance Frameworks
      • Examples: SOC 2, FedRAMP, PCI, NIST
    • Data Sensitivity
      • Examples: PII, Financial Data, Confidential
  • Project Details
    • Repos Relating to a Particular Application
      • Examples: Application A, Application B, Microservice \- App A
    • Business Function
      • Examples: Internal, Customer-Facing Application, Client A
    • Stack
      • Examples: Back-End, Front-End, Mobile
    • Technology
      • Examples: React, Django, Azure, Reusable GitHub Actions, API
    • Status
      • Examples: In Development, Maintenance Mode, Legacy Project
    • Environment
      • Examples: Prod, Dev, QA, Demo, POC
  • Policy/Management Groups
    • Security Policy
      • Examples: GHAS Required, Secret Scanning Required, Dependency Review Required
    • Repo Policy
      • Examples: Standard Branch Protections Required
  • Business Unit
    • Areas of Responsibility
      • Examples: Acquisition X, DevOps, IT, Legal, HR

Tips to Remember

  • Leverage the Custom Properties API
  • You can reference custom properties as part of events in GitHub Actions: github.event.repository.custom_properties.[PROPERTY]
  • You can filter on custom properties in the “Repositories” tab of your organization as well as Security Overview dashboard in the “Security” tab
  • You can use custom properties to filter on repos you’d like to automatically assign repo ruleset or security configurations to

Happy developing!