.. _jenkins-infra:

#######
Jenkins
#######

.. _jenkins-upgrade:

Upgrading Jenkins
=================

Regular Jenkins maintenance is necessary to ensure security patches are up to
date.

Follow these steps to update Jenkins:

#. Notify community that maintenance is about to begin
#. Put Jenkins into Shutdown mode
   (https://jenkins.example.org/quietDown)
#. ``yum update -y --exclude=jenkins``
   (Do this step while waiting for Jobs to clear in shutdown mode.)
#. ``yum update -y``
#. Update Jenkins plugins via Manage Jenkins > Manage Plugins

   Ensure that you click "Download now and install after restart" but DO NOT
   check the "Restart Jenkins when installation is complete and no jobs are
   running" button.

#. Restart the server itself ``systemctl reboot``
#. Remove Shutdown mode from Jenkins
   (https://jenkins.example.org/cancelQuietDown)

.. _jenkins-github:

GitHub Configuration
====================

Jenkins requires admin level configuration to work with GitHub.

#. Create a GitHub account for Jenkins to use

   The user needs to have Full Admin access to the GitHub Organization that
   Jenkins will manage, this is so that Jenkins can automatically manage the
   hooks.

#. Navigate to ``https://jenkins.example.org/configure``
#. Under ``GitHub Servers`` click *Advanced* >
   *Manage GitHub actions* > *Convert login and password to token*
#. Choose ``From login and password`` and enter the github-jenkins account details
#. Click Create token credentials
#. Under ``GitHub Servers`` click *Add GitHub Server* and configure the following:

   .. code-block:: none

      Name: <Leave blank>
      API URL: https://api.github.com
      Credentials: <Auto-generated token>
      Manage hooks: true
      GitHub client cache size (MB): 20

#. Click ``Re-register hooks for all jobs``

.. _jenkins-security:

Security Configuration
======================

Security recommendations for Jenkins.

#. Install the `OWASP Markup Formater Plugin
   <https://plugins.jenkins.io/antisamy-markup-formatter/>`_
#. Navigate to `https://jenkins.example.org/configureSecurity/`
#. Configure the following:

   * Enable ``CSRF Protection`` with ``Default Crumb Issuer``
   * Enable ``Agent -> Master Access Control``
   * Disable ``JNLP Protocol 1 - 3``
   * Enable ``JNLP Protocol 4``
   * Set ``Markup Formatter`` to ``Safe HTML``