User Guide¶

This guide is aimed at developers who use otterdog to manage GitHub organizations and repositories via an existing otterdog setup.

It focuses on the day-to-day workflow for making changes through configuration and pull requests, not on operating otterdog itself, see Operating Otterdog for that.

Making changes¶

Every change to the configuration of an organization is a pull request on its configuration repository:

• Workflow for changes: from the configuration repository to the changes applied on GitHub.
• Adding resources: declare a new resource, e.g. a repository, with the function of the default configuration.
• Renaming resources: rename a resource without deleting and recreating it.
• Removing resources: delete a resource from the configuration.

Configuration Guides¶

The Configuration Guides start from common needs, e.g. protecting branches and tags, securing GitHub Actions or managing secrets, and explain how to address them with otterdog, including the trade-offs and limitations to consider. Start with the fundamentals: Inherited and explicit values and Reusing configuration with Jsonnet.

Troubleshooting & limits¶

• Troubleshooting: understand a message of validate or an unexpected result of plan and apply.
• Unsupported settings: the features and settings of GitHub that otterdog cannot manage.