Configuring

This plugins accepts one repository template per organization and can be configured with any Git server, it can clone both public and private repositories.

To configure it, install the command line and login to your hoop gateway instance.

shell
hoop login

Public Repositories

Only the Git URL is required.

Required Configuration:

GIT_URL (required) - the GIT URL of the repository (http or ssh)

shell
hoop admin create plugin runbooks --overwrite \
	-c GIT_URL=https://github.com/hoophq/runbooks

configure runbooks plugin (public repository)

Basic Credentials

It uses username and password to clone a repository via HTTP.

Required Configuration:

GIT_URL (required) - the HTTP GIT URL of the repository

GIT_USER (optional) - the git username, defaults to oauth2 if it’s empty

GIT_PASSWORD (required) - the password or token that has read access to the repository

GitHub users could use personal tokens

shell
hoop admin create plugin runbooks --overwrite \
	-c GIT_URL=https://github.com/hoophq/runbooks \
  -c GIT_PASSWORD=<GIT-PWD>

configure runbooks plugin (basic credentials)

SSH Private Keys

It uses a private key to clone the repository via SSH.

Required Configuration:

GIT_URL (required) - the SSH GIT URL of the repository

GIT_SSH_KEY (required) - the private key that has read access to the repository

GIT_SSH_USER (optional) - the git username, defaults to git if it’s empty

GIT_SSH_KEYPASS (optional) - the password of the key

GitHub users could follow this article to set up a deploy key to a repository.

shell
hoop admin create plugin runbooks --overwrite \
	-c GIT_URL=https://github.com/hoophq/runbooks \
  -c GIT_SSH_KEY=path:/path/to/private-key

configure runbooks plugins (ssh private keys)

💡

Note that the -c option accepts the prefix path: to indicate to load a file from a filesystem and use it as input to the key GIT_SSH_KEY

Testing

To test the integration, issue the command below, it will return the last commit from the directory. When you add a runbook file it will show in the items attribute.

Visit the webapp to start executing runbooks from connections.

shell
hoop admin get runbooks -o json
{"items":[],"commit":"<git-sha>","commit_author":"author <author@email.tld>","commit_message":"<msg>\n"}

Configuring Connections

Connections are associated with plugins and can define the prefix of runbooks that will be available for a particular connection. This option allows for limiting access to runbooks per connection. Therefore, the following configuration:

shell
hoop admin create conn pg -a main --overwrite \
  --plugin runbooks:team/dba -- echo

hoop admin create conn python3-scripts -a main --overwrite \
  --plugin runbooks:team/finops -- echo

Allows the python3-scripts connection to list and execute any runbook at team/finops/ folder and subfolders

Allows the pg connection to list and execute any runbook at team/dba/ folder and subfolders

plain text
├── README.md
└── team
    ├── dba
    │   └── ops
    │       └── charge.runbook.py
    └── finops
        └── sql
            └── fetch-customer.runbook.sql

git runbooks directory example structure

💡

Note that these connections are just examples to illustrate how runbooks works.