Skip to content

Getting started

How you start with otterdog depends on what you want to do. Most people only change the configuration of an organization through pull requests and never install anything.

Change the configuration of an organization

For the members and contributors of a project whose GitHub organization is managed by otterdog.

  1. Find the configuration repository of the organization, e.g. .eclipsefdn for the projects of the Eclipse Foundation. The configuration of the organization is otterdog/<organization>.jsonnet, and the dashboard shows the current one of each organization of the Eclipse Foundation.
  2. Find what to change: the Configuration Guides start from a need, e.g. protecting a branch or providing a secret to a workflow, the Reference documents every property. The configuration only declares what differs from the default configuration, see Inherited and explicit values.
  3. Try it out (optional): the Playground evaluates a configuration and checks its values like otterdog does.
  4. Open a pull request on the configuration repository: otterdog validates it and shows the changes it would make on GitHub, the configured teams review it, and the changes are applied once it is merged.

Next: Workflow for changes, then adding, renaming or removing resources.

Manage organizations with the command line tool

For the administrators of GitHub organizations, who apply configurations themselves.

  1. Install git and otterdog, see Install:

    pipx install otterdog

  2. Configure the organizations to manage in an otterdog.json file: the default configuration to use and the credentials to access each organization (a GitHub token, and a GitHub account with two-factor authentication for the settings only available in the web interface), see Setup.

  3. Import the current configuration of an organization, then review and apply changes:

    otterdog import <organization>   # writes the configuration of the organization from its live settings
otterdog plan <organization>     # shows the changes that would be applied
otterdog apply <organization>    # applies them

Next: Usage of the command line tool and the CLI Operations.

Deploy otterdog for your organizations

For the operators who run the otterdog GitHub App, which validates the pull requests of configuration repositories, applies the merged changes and provides the dashboard and its Playground.

  1. Create a GitHub App and install it in the organizations to manage.
  2. Deploy the container image with the Helm chart on Kubernetes, and initialize otterdog.
  3. Define the policies shared by your organizations: the default configuration, validation scripts and exceptions, see Organization-wide policies.

Next: Otterdog WebApp.

Contribute to otterdog

For the developers of otterdog itself.

  1. Set up a development environment with make init, see Development Setup.
  2. Read the Architecture and the Coding & Style Guidelines.
  3. Propose your change as described in the Contribution Workflow.

Next: Testing and the Release Process.