Package: otterdog
OtterdogIntroductionOtterdog is a tool to manage GitHub organizations at scale using a configuration as code approach.
It is actively developed by the Eclipse Foundation and used to manage its numerous projects hosted on GitHub.QuickstartOtterdog Presentation @ Open Source Summit 2023Default Configuration used @ Eclipse FoundationDocumentationThe documentation is available atotterdog.readthedocs.io.Build instructionsSystem requirements:python3.10 (mandatory): install usingapt install python3poetry (mandatory): install usingcurl -sSL https://install.python-poetry.org | python3 -orpipx install poetrygo (mandatory for installing jsonnet-bundler): install usingapt install golangjsonnet-bundler (mandatory): install usinggo install -a github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@v0.5.1bitwarden cli tool (optional): install usingsnap install bwpass cli tool (optional): install usingapt install passBuilding StepsCreate a virtual python environment and install necessary python dependencies using poetry:$makeinitTesting build$./otterdog.sh-hSetupThe general configuration for supported organizations and their corresponding credentials in order
to access their GitHub settings has to be placed in a json file (default:otterdog.json, can be changed
with the-cflag):{..."organizations":[{"name":"<org name>","github_id":"<github org id>","credentials":{"provider":"<bitwarden | pass>",...// provider specific data}}]...}CredentialsOtterdog needs certain credentials to access information from an organization and its repositories on GitHub:username / password / 2FA seedAPI tokenThe login / username / 2FA seed are required to access the web interface of GitHub in order to retrieve certain
settings that are not accessible via its rest / graphql API.The GitHub api token needs to have the following scopes enabled:repoworkflowadmin:orgadmin:org_hookdelete_repoThe credentials can be stored in different providers (bitwarden, pass).BitwardenWhen usingbitwardento store the credentials, you need to enter a validitem idas additional credential data:{..."organizations":[{"name":"<org name>","github_id":"<github org id>","credentials":{"provider":"bitwarden","item_id":"<bitwarden item id>"}}]...}The item stored in bitwarden needs to contain the following information (a sample json output of such an item):{"object":"item","id":"<bitwarden item id>","name":"<item name>","fields":[{"name":"api_token_admin","value":"<github API token>"}],"login":{"username":"<github username>","password":"<github password>","totp":"<github TOTP text code>"}}Mandatory items:Field with name "api_token_admin" and as value the GitHub token to access the organizationlogin.usernameof a user that can access the organization with enabled 2FAlogin.passwordthe password of that userlogin.totpthe TOTP text codePassWhen usingpassto store the credentials, you need to enter fully qualified pass names to access the various
required credential data:{..."organizations":[{"name":"<org name>","github_id":"<github org id>","credentials":{"provider":"pass","api_token":"<path/to/api_token>","username":"<path/to/username>","password":"<path/to/password>","2fa_seed":"<path/to/2fa_seed>"}}]...}In case your password storage dir is not located at the default location, you can
configurate that in thedefaults:{"defaults":{"pass":{"password_store_dir":"path/to/storage/dir"}}}UsageRun theimportoperation to retrieve the current live configuration for an organization:$otterdog.shimport<organization>The created configuration file for the organization can be found at<data-directory>/orgs/<organization>.jsonnetRun theplanoperation to highlight differences between the live configuration and the written configuration:$otterdog.shplan<organization>Runapplyoperation to reflect the written configuration on github itself:$otterdog.shapply<organization>Container Runtime (Linux/MacOS)RequirementsAn otterdog.json already in your current directory(Recommended) a directory orgsBuilding Container ImageCreating a container local imagemake container_buildBuilding a Development Container ImageCreating a container development local imagemake container_build_devRunning otterdog in a containerUsing Bitwarden clientFirstly you need to login and unlock your Bitwarden session by executing the command belowbw loginbw unlockAs result, you will get a token session. Please follow example below to make available in your terminal (Linux/MacOS)export BW_SESSION="ffdsajklloremipsumfxs000f000r0loremipsum"Using pass clientPass needs to be already installed as well as configured with all data needed inotterdog.jsonby executingpassin your profileActivating Otterdog Container RuntimeActivate otterdog environment will create an aliasotterdogsource scripts/bin/active-otterdogChecking otterdog aliasotterdog -hDeactivating otterdog environmentdeactivate-otterdogotterdog container ArgumentsAn table argumentsArgumentDescription-g.gnupg directory PATH by default $HOME/.gnupg if it is not provided-oOutput ORGS directory path by default $PWD/orgs if it is not provided-cotterdog json file path by default $PWD/otterdog.json if it is not provided-p.password-store directory PATH by default $HOME/.password-store if it is not provided-hHelp about container arguments and otterdogPlease find below an example to show configurationotterdog -c $PWD/otterdog.json -g $HOME/.gnupg -o $PWD/orgs apply -fUsage Otterdog Container RuntimePlease follow the sectionUsagePlease bear in mind that all command need to drop.shActivating Development Otterdog Container RuntimeActivating development otterdog environment will run eclipse/otterdog:dev. Thus it can be used container shell. Please find below an exampleexport OTTERDOG_DEV=1; source scripts/bin/active-otterdogotterdog /bin/bashTo activate development otterdog environment with argumentexport OTTERDOG_DEV=1; source scripts/bin/active-otterdogotterdog -c $PWD/otterdog.json -g $HOME/.gnupg -o $PWD/orgs /bin/bashChecking otterdog environment/app/otterdog.sh -hDeactivating development otterdog runtime typeexitthendeactivate-otterdogUsage Development Otterdog Container RuntimePlease follow the sectionUsageCleaning container environmentPlease use the macro belowmake container_cleanKnown issues