⚙️ Syncing GitHub repository settings at scale

How to configure GitHub repositories using config files, enabling Pull Requests for repository settings

I’ve been using GitHub's "Settings" App to easily sync and maintain repository settings, as well as streamline the creation and configuration of new repositories. Today I’ll go through why I use it, its use cases, and how to avoid common pitfalls that I’ve faced! 😊

Why should I sync settings using a config file?

Synchronizing settings via a config file enhances consistency, efficiency, and transparency. It empowers teams to propose changes via Pull Requests, ensuring a democratized and traceable approach to repository configurations.

This is more evident when managing open source repositories, and even more critical at scale, when managing tens if not hundreds of repos. For example, if you have 10 repositories, you would need to manually update 10 repositories to add a new collaborator. With the GitHub "Settings" App, you can simply update the config file and create a Pull Request to update all 10 repositories. The same goes for label management, branch protections, and more.

Another benefit of using the GitHub "Settings" App is that it allows you to easily create new repositories with the correct settings. This is especially useful when you want to quickly create a new repository with the same settings as you're already used to, without having to manually configure them. I found that this streamlines my workflow of new project creation, and also ensures that I don't forget to add any important settings that I would otherwise stumble upon later.

How can I implement this?

To utilize this functionality, first, install the GitHub "Settings" App and choose which repositories you'd like it to have access to. I select "All repositories" so it applies to current and also future repos automatically.

Next, if you intend to use a single file to manage multiple repositories, it's a good idea to create a dedicated repository for this, called YOUR_ORG_NAME/.github, e.g. https://github.com/rogerluan/.github. This allows you to create a centralized config file, which will then be inherited in all the other repos you want to manage. Keep in mind you should still create a .github/settings.yml file in each repository you want to manage, as this is where the app will look for the settings file, but then you can simply point it to the centralized file. Here's a sample "child" file: https://github.com/rogerluan/arkana/blob/main/.github/settings.yml

Then, define the repository settings in a file named .github/settings.yml. This includes specifying details like collaborators, issue labels, and branch protections. As far as I can tell, the way this app works is that it will parse the raw yaml file and anything that is in it will be sent directly into GitHub's API and be used to update the settings. This means that there's no official list of supported settings for this app, as you can pass anything that is supported by the GitHub API, so the GitHub's API is what should be considered the source of truth.

For a sample list of settings, you can check out the GitHub "Settings" App documentation or if you prefer, there's also my personal settings file that I use for my repositories.

Common Issues

When configuring your file, a small typo, indentation issue, or use of unsupported settings can cause the app to fail, and it fails silently. So it's common to find users frustrated, complaining that the settings aren’t syncing, because there's no user feedback pointing out what's wrong with your file. To overcome this issue, I suggest using a setting file that already works, and go from there. I particularly had issues configuring branch protection and topics (topics can’t have spaces, FYI), but if you follow my file, you should be fine!

Another very important issue to keep in mind is the security implications of using this app. The app will have write access to all the repositories you grant it access to, so it's important to keep your settings file secure. I strongly recommend adding mechanisms to prevent PRs from being merged without someone reviewing that the settings file is being changed (e.g. CODEOWNERS feature, danger code review to check if the settings file is being changed). Failing to do so could be catastrophic, as it would allow anyone to change your repository settings without your knowledge, like changing branch protection rules, adding collaborators, or even making repositories public.

Conclusion

The GitHub "Settings" App significantly simplifies repository settings management at scale, and I love using it for my open source projects! Its ability to centralize configuration and enable Pull Requests for settings adjustments makes it an invaluable tool for modern development workflows.

For more detailed information on the GitHub "Settings" App, you can visit their official page: GitHub Apps - Settings.