otterdog¶
Otterdog manages GitHub organizations at scale with a configuration as code approach: the settings of an organization and of its repositories are declared in Jsonnet, reviewed as pull requests and applied to GitHub. It is developed by the Eclipse Foundation, which uses it to manage the GitHub organizations of its projects.
How it works¶
Declare
A repository of the organization declares its settings, teams and repositories in Jsonnet.
Propose
Anyone proposes a change as a pull request, tried out in the Playground if needed.
Review
otterdog validates it and shows what it would change on GitHub, the configured teams approve.
Apply
Once the pull request is merged, otterdog applies the changes to the GitHub organization.
The configuration only declares what differs from a default configuration shared
by many organizations, and administrators can also apply changes with the otterdog command line tool. See
Workflow for changes for the steps of a change.
What otterdog manages¶
- Organizations: settings, roles, teams, webhooks, secrets and variables, rulesets, custom properties and code security configurations.
- Repositories: settings, branch protection rules and rulesets, environments, webhooks, secrets and variables.
- Across organizations: policies enforce a behavior, and blueprints keep files and settings present in repositories by opening pull requests.
Some settings are only available in the web interface of GitHub, otterdog manages them through a browser session. Others cannot be managed at all, see Unsupported settings.
Where to go next¶
-
Getting started
Find the path that matches your role: change the configuration of an organization, manage organizations with the command line tool or deploy otterdog.
-
User Guide
Make a change, then follow the configuration guides: protect branches and tags, secure GitHub Actions, manage secrets, teams and repositories.
-
Reference
Every resource and property of a configuration, the policies, the blueprints and the operations of the command line tool.
-
Dashboard and Playground
Browse the organizations managed by otterdog at the Eclipse Foundation and their configuration. Its Playground evaluates a configuration in your browser and checks its values like otterdog does, before you open a pull request: every complete example of the guides opens in it.
-
Operating otterdog
Install the command line tool or deploy the GitHub App, set up credentials and the default configuration of your organizations.
-
Developing otterdog
Set up a development environment, understand the architecture and contribute to otterdog.