Blame doc/usage/pagure_ci_jenkins.rst

Pierre-Yves Chibon 585425
Jenkins with Pagure-ci
Pierre-Yves Chibon 585425
======================
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Jenkins is a Continuous Integration service that can be configured to be
Pierre-Yves Chibon 585425
integrated with pagure.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
This document describe the steps needed to make it work.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 71a995
How does it work?
Pierre-Yves Chibon 71a995
-----------------
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
The principal is:
Pierre-Yves Chibon 71a995
* pagure will trigger a build on jenkins when a pull-request is created,
Pierre-Yves Chibon 71a995
  updated or when someone explicitely asks pagure to do so or when a new commit
Pierre-Yves Chibon 71a995
  is pushed (if pagure-ci is configured to trigger on commit).
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
* pagure will send a few information to jenkins when triggering a build:
Pierre-Yves Chibon 71a995
  ``REPO``, ``BRANCH``, ``BRANCH_TO``, ``cause``.
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
* jenkins will do its work and, using webhook, report to pagure that it has
Pierre-Yves Chibon 71a995
  finished its task
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
* pagure will query jenkins to know the outcome of the task and flag the PR
Pierre-Yves Chibon 71a995
  accordingly
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
``REPO`` corresponds to the url of the repository the pull-request originates
Pierre-Yves Chibon 71a995
from (so most often it will be a fork of the main repository).
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
``BRANCH`` corresponds to the branch the pull-request originates from (the
Pierre-Yves Chibon 71a995
branch of the fork).
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
``BRANCH_TO`` corresponds to the targeted branch in the main repository (the
Pierre-Yves Chibon 71a995
branch of the main project in which the PR is to be merged).
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 71a995
``cause`` is the reason the build was triggered (ie: the pull-request id or the
Pierre-Yves Chibon 71a995
commit hash).
Pierre-Yves Chibon 71a995
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
How to enable Pagure CI
Pierre-Yves Chibon 2323af
-----------------------
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Visit the settings page of your project
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Scroll down to the `Hooks` section and click on `Pagure CI`
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Select the type of CI service you want
Pierre-Yves Chibon 585425
Clement Verna dd6f03
* Enter the URL of the CI service. For example `http://jenkins.fedoraproject.org`
Pierre-Yves Chibon 585425
Clement Verna dd6f03
* Enter the name of the job the CI service will trigger. For example `pagure-ci`
Clement Verna dd6f03
Clement Verna dd6f03
* Tick the checkbox activating the hook. Either trigger on every commits, trigger only
Lubomír Sedlář 250277
  on pull-requests or both every commits and pull-requests.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
These steps will activate the hook, after reloading the page or the tab, you
Pierre-Yves Chibon 585425
will be given access to two important values: the token used to trigger the
Pierre-Yves Chibon 585425
build on jenkins and the URL used by jenkins to report the status of the
Pierre-Yves Chibon 585425
build.
Pierre-Yves Chibon 585425
Keep these two available when configuring jenkins for your project.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Configure Jenkins
Pierre-Yves Chibon 2323af
-----------------
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
These steps can only be made by the admins of your jenkins instance, but
Pierre-Yves Chibon 585425
they only need to be made once.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Download the following plugins:
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
  * `Git Plugin <https: display="" git+plugin="" jenkins="" wiki.jenkins-ci.org="">`_</https:>
Pierre-Yves Chibon 585425
  * `Notification Plugin <https: display="" jenkins="" notification+plugin="" wiki.jenkins-ci.org="">`_</https:>
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Configure your project on Jenkins
Pierre-Yves Chibon 2323af
---------------------------------
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Go to the `Configure` page of your project
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Under `Job Notification`  click `Add Endpoint`
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Fields in Endpoint will be :
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
::
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
    FORMAT: JSON
Pierre-Yves Chibon 585425
    PROTOCOL: HTTP
Pierre-Yves Chibon 0dde14
    EVENT: All Events
Pierre-Yves Chibon 585425
    URL: <the ci="" hook="" in="" on="" pagure="" provided="" the="" url=""></the>
Pierre-Yves Chibon 585425
    TIMEOUT: 3000
Pierre-Yves Chibon 585425
    LOG: 1
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Tick the checkbox `This build is parameterized`
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Add two `String Parameters` named REPO and BRANCH
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Source Code Management select Git  and give the URL of the pagure project
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Under Build Trigger click on Trigger build remotely and specify the token
Pierre-Yves Chibon 585425
  given by pagure.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* Under Build -> Add build step -> Execute Shell
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
* In the box given  enter the shell steps you want for testing your project.
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
Example Script
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
::
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
    # Script specific for Pull-Request build
Pierre-Yves Chibon 585425
    if [ -n "$REPO" -a -n "$BRANCH" ]; then
Pierre-Yves Chibon 585425
    git remote rm proposed || true
Pierre-Yves Chibon 585425
    git remote add proposed "$REPO"
Pierre-Yves Chibon 585425
    git fetch proposed
Pierre-Yves Chibon 585425
    git checkout origin/master
Pierre-Yves Chibon 585425
    git config --global user.email "you@example.com"
Pierre-Yves Chibon 585425
    git config --global user.name "Your Name"
Pierre-Yves Chibon 585425
    git merge --no-ff "proposed/$BRANCH" -m "Merge PR"
Pierre-Yves Chibon 585425
    fi
Pierre-Yves Chibon 585425
Pierre-Yves Chibon 585425
    # Part of the script specific to how you run the tests on your project