arc/docs/webhook2fedmsg/index.rst

webhook2fedmsg
==============

Purpose
-------

This investigation's goal is to explore a possible new application that will convert
webhooks from different services to Fedora messaging messages.

Resources
---------

- Initiative proposal: https://pagure.io/cpe/initiatives-proposal/issue/18

Requirements
------------

- User can log in using FAS account
- User can link different webhook services to FAS account
- Application will listen for the webhook POST requests
- Application will provide endpoint for each service
- POST request will be validated against the known tokens for the service
- Support for `GitHub
  <https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks>`_
- Support for `Discourse
  <https://meta.discourse.org/t/configure-webhooks-that-trigger-on-discourse-events-to-integrate-with-external-services/49045>`_
- CI - Recommending `Zuul CI <https://fedoraproject.org/wiki/Zuul-based-ci>`_ or `Github
  Actions <https://github.com/features/actions>`_
- Documentation - Documentation could be hosted on `readthedocs.org
  <https://readthedocs.org/>`_
- OpenShift deployment
- Unit tests - Recommending `tox <https://tox.wiki/en/latest/>`_
- Fedora messaging schema
- Easy to use dev env - Recommending either `vagrant <https://www.vagrantup.com/>`_ or
  containerized environment

Nice to have
------------

List of features that would be nice to have.

- Document how to create webhooks on every service
- Document how to generate token on every service
- Support for `GitLab <http://mmb.irbbarcelona.org/gitlab/help/web_hooks/web_hooks.md>`_
- Support for `MediaWiki <https://www.mediawiki.org/wiki/Extension:EventBus>`_
- Automatic dependency management - Recommending `renovate
  <https://docs.renovatebot.com/>`_
- API for managing tokens
- Automatic deployment in OpenShift

Investigation
-------------

Following it the design document for webhook2fedmsg.

.. toctree::
    :maxdepth: 1

    design_of_webhook2fedmsg

Implementation
--------------

The implementation details of the project can be found here.

.. toctree::
    :maxdepth: 3

    the_action_plan

The Good Points
---------------

1. Supports multiple webhook services
2. Easier to maintain - less codebases
3. Easier to add new webhook service in future
4. Users can manage tokens by themselves
5. With this solution we don't need to rewrite github2fedmsg - one less initiative

The Bad points
--------------

1. Initial work - completely new app
2. Another application to maintain - However this will allow us to get rid of few others
3. Manual work with tokens and webhooks on webhook service side for users

Conclusions
-----------

This application will help us to lower our codebase. We wouldn't need to maintain
multiple applications service2fedmsg anymore, but everything that provides webhook could
be managed by this application. It is definitely something we have knowledge and skills
to do.

Proposed Roadmap
----------------

- Step 1 - Write new app with tests and documentation
- Step 2 - Create separate repository with message schemas
- Step 3 - Deploy in staging
- Step 4 - Inform community this service is available for testing
- Step 5 - Deploy in production
- Step 6 - Community blog announcing this new service

Estimate of work
----------------

This work will need at least 2 developers, one with web frontend skill set. The
estimation for this project is 12 weeks.