https://github.com/esss/jenkins-to-github-notify
Notify build status using a Jenkins Webhook
https://github.com/esss/jenkins-to-github-notify
Last synced: about 1 year ago
JSON representation
Notify build status using a Jenkins Webhook
- Host: GitHub
- URL: https://github.com/esss/jenkins-to-github-notify
- Owner: ESSS
- License: mit
- Archived: true
- Created: 2022-07-21T13:15:13.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-14T16:44:01.000Z (over 2 years ago)
- Last Synced: 2025-02-27T02:29:48.619Z (over 1 year ago)
- Language: Python
- Size: 35.2 KB
- Stars: 1
- Watchers: 18
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
========================
jenkins-to-github-notify
========================
Notify build status using a Jenkins Webhook.
This service receives events posted by Jenkins WebHooks and updates `GitHub commit status API `_.
Installation
============
This repository contains a ``Dockerfile`` which can be used to build an image, which can then be run in any server.
Service configuration
---------------------
Place a ``.env`` file in the current working directory where the service is started::
JENKINS_URL=https://some-server.com/jenkins
JENKINS_USERNAME=jenkins-bot
JENKINS_PASSWORD=PASSWORD_FOR_JENKINS_BOT
JENKINS_SECRET=GENERATED_SECRET
GH_TOKEN=GITHUB_TOKEN
* ``JENKINS_URL``: full URL to the Jenkins server.
* ``JENKINS_USERNAME``: user name to access the Jenkins API.
* ``JENKINS_PASSWORD``: password or token for ``JENKINS_USERNAME``. Prefer tokens when possible as they can be easily revoked and has less permissions.
* ``JENKINS_SECRET``: this is a secret that will be sent by the Web Hook and verified by the service to ensure the requests are coming from the expected place.
Can be generated easily with:
.. code-block:: python
>>> import secrets
>>> secrets.token_hex()
'GENERATED TOKEN'
This same secret will be used in the Jenkins configuration below.
* ``GH_TOKEN``: a `personal access token `__ with ``repo`` permissions to the repositories that will have their status updated.
Jenkins configuration
---------------------
Go to *Configure System*, and enter a new *Web Hook*:
* Enter the address/port where the container is running.
* Enter a timeout (30s is fine).
* Click *Advanced*, uncheck *All Events*, and mark:
- ``jenkins.job.started``
- ``jenkins.job.completed``
For both of them, *customize* the URL with::
${url}?event=${event.name}&build_number=${run.number}&job_name=${run.project.name}&url=${run.getUrl()}&secret=JENKINS_SECRET
Replace ``JENKINS_SECRET`` with the value of the ``JENKINS_SECRET`` variable.
Development
===========
Create a virtual environment for Python 3.10, activate it, then execute:
.. code-block:: console
pip install pip-tools
pip-sync
pre-commit install
To run the tests:
.. code-block:: console
pytest
Deployment
==========
There is a ``deploy`` workflow which is `triggered manually `__.
The inputs are:
* ``version``: the ref version to push, usually a tag.
* ``push``: if we should push the build image to the configured docker registry or not.
This workflow uses these organization/repository secrets:
* ``docker_registry``: the URL of the docker registry used to login.
* ``docker_registry_push_url``: the URL where we should push images to.
* ``docker_push_user``: user name with has push access to the registry.
* ``docker_push_password``: password of the user.
Similar projects
================
There are Jenkins plugins which do something similar, but did not met all our requirements:
* `GitHub plugin `_: also reports build status, however it does not work
for multiple repositories (see `JENKINS-28177 `_).
* `GitHub Checks plugin `_: unfortunately requires a more complex setup requiring
a GitHub App for authentication, and seems (but not 100% sure) to require setting up a special "github project"
in Jenkins (instead of a normal Git repository).
License
=======
MIT.