Skip to content
This repository has been archived by the owner on May 28, 2024. It is now read-only.

ESSS/jenkins-to-github-notify

Repository files navigation

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:

    >>> 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:

pip install pip-tools
pip-sync
pre-commit install

To run the tests:

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.