OCA GitHub bot

The goal of this project is to collect in one place:

• all operations that react to GitHub events,
• all operations that act on GitHub repos on a scheduled basis.

This will make it easier to review changes, as well as monitor and manage these operations, compared to the current situations where these functions are spread across cron jobs and ad-hoc scripts.

Table of contents

• Features
  • On pull request close
  • On push to main branches
  • On Pull Request review
  • On Pull Request CI status
  • Commands
  • TODO (help wanted)
• Developing new features
• Running it
  • Environment variables
  • Using docker-compose
• Development
• Contributors
• Maintainers

Features

On pull request close

Auto-delete pull request branch

When a pull request is merged from a branch in the same repo, the bot deletes the source branch.

On push to main branches

Repo addons table generator in README.md

For addons repositories, update the addons table in README.md.

Addon README.rst generator

For addons repositories, generate README.rst from readme fragments in each addon directory, and push changes back to github.

Addon icon generator

For addons repositories, put default OCA icon in each addon that don't have yet any icon, and push changes back to github.

setup.py generator

For addons repositories, run setuptools-odoo-make-defaults, and push changes back to github.

These actions are also run nightly on all repos.

Also nightly, wheels are generated for all addons repositories and rsynced to a PEP 503 simple index.

On Pull Request review

When there are two approvals, set the approved label. When the PR is at least 5 days old, set the ready to merge label.

On Pull Request CI status

When the CI in a Pull Request goes green, set the needs review label, unless it has wip: or [wip] in it's title.

Commands

One can ask the bot to perform some tasks by entering special commands as merge request comments.

/ocabot merge optionally followed by one of major, minor, patch, can be used to ask the bot to the following:

• rebase the PR on the target branch
• run the main branch operations (see above) on it
• optionally bump the version number of the addons modified by the PR
• merge when tests on the rebased branch are green
• when the version was bumped, generate a wheel and rsync it to the PEP 503 simple index

TODO (help wanted)

See our open issues, pick one and contribute!

Developing new features

The easiest is to look at examples.

New webhooks are added in the webhooks directory. Webhooks execution time must be very short and they should delegate the bulk of their work as delayed tasks, which have the benefit of not overloading the machine and having proper error handling and monitoring.

Tasks are in the tasks directory. They are Celery tasks.

Tasks can be scheduled, in cron.py, using the Celery periodic tasks mechanism.

Running it

Environment variables

First create and customize a file named environment, based on environment.sample.

Tasks performed by the bot can be specified by setting the BOT_TASKS variable. This is useful if you want to use this bot for your own GitHub organisation.

Using docker-compose

docker-compose up --build will start

• the bot, listening for webhooks calls on port 8080
• a celery worker to process long running tasks
• a celery beat to launch scheduled tasks
• a flower celery monitoring tool on port 5555

The bot URL must be exposed on the internet through a reverse proxy and configured as a GitHub webhook, using the secret configured in GITHUB_SECRET.

Development

This project uses black as code formatting convention, as well as isort and flake8. To make sure local coding convention are respected before you commit, install pre-commit and run pre-commit install after cloning the repository.

To run tests, type tox. Test are written with pytest.

Here is a recommended procedure to test locally:

• Prepare an environment file by cloning and adapting environment.sample.
• Load environment in your shell, for instance with bash:

set -o allexport
source environment
set +o allexport

• Launch the redis message queue:

docker run -p 6379:6379 redis

• Install the maintainer tools and add the generated binaries to your path:

PATH=/path/to/maintainer-tools/env/bin/:$PATH

• Create a virtual environment and install the project in it:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -e .

• Then you can debug the two processes in your favorite IDE:
  • the webhook server: python -m oca_github_bot
  • the task worker: python -m celery worker --app=oca_github_bot.queue.app --pool=solo --loglevel=INFO
• To expose the webhook server on your local machine to internet, you can use ngrok
• Then configure a GitHub webhook in a sandbox project in your organization so you can start receiving webhook calls to your local machine.

Contributors

• Stéphane Bidoul <[email protected]>
• Holger Brunn <[email protected]>
• Miquel Raïch <[email protected]>
• Florian Kantelberg <[email protected]>
• Laurent Mignon <[email protected]>
• Jose Angel Fentanez <[email protected]>
• Simone Rubino <[email protected]>

Maintainers

This module is maintained by the OCA.

OCA, or the Odoo Community Association, is a nonprofit organization whose mission is to support the collaborative development of Odoo features and promote its widespread use.