datagov-deploy-jenkins

Ansible role to install Jenkins for the Data.gov platform.

Features

• Production single-instance Jenkins
• SSL termination with Nginx
• Automatic updates for plugins

Plugins

The following plugins are installed. You may install additional plugins by specifying them in the jenkins_additional_plugins variable.

• ansible allows to execute Ansible tasks as a job build step
• ansicolor (enable in pipeline) add ANSI escape sequences, including color, to Console Output
• audit-trail (requires configuraiton) keeps a log of who performed particular Jenkins operations, such as configuring jobs
• aws-credentials allows storing Amazon IAM credentials within the Jenkins Credentials API
• configuration-as-code an opinionated way to configure Jenkins based on human-readable declarative configuration files
• blueocean is a new Jenkins UI optimized for user experience; it reduces clutter and increases clarity for every member of your team
• github integrates Jenkins with GitHub projects
• github-issues create GitHub issues on build failures
• job-dsl define jobs in a programmatic form in a human readable file
• packer allows Packer tasks to build and publish AMI and OS images
• periodicbackup (requires configuration) allows archiving and restoring your Jenkins (and Hudson) home directory
• pipeline-utility-steps adds small, miscellaneous, cross platform utility steps for Pipeline Plugin jobs
• role-strategy adds a new role-based strategy to manage users' permissions
• saml (requires configuration) allows authentication to Jenkins via the SAML 2.0 protocol
• ssh-agent allows you to provide SSH credentials to builds via a ssh-agent in Jenkins
• timestamper (enable in pipeline) adds timestamps to the Console Output
• workflow-aggregator a.k.a. Pipeline, a suite of plugins that lets you orchestrate simple or complex automation
• ws-cleanup (requires configuraiton) declared build wrapper and post build step to delete files matching a pattern

Usage

This role assumes you've already installed nginx. Add this role and its dependencies to your requirements.yml file.

---
- src: https://github.com/GSA/datagov-deploy-jenkins
  version: v1.0.0
  name: gsa.datagov-deploy-jenkins
- src: geerlingguy.jenkins
- src: nginxinc.nginx

Install with ansible-galaxy.

$ ansible-galaxy install -r requirements.yml

Example playbook.

---
- name: Install
  hosts: all
  roles:
    - nginxinc.nginx
    - gsa.datagov-deploy-jenkins

Variables

In addition to the variables available for geerlingugy.jenkins, these variables are also available.

jenkins_admin_user string (default: admin)

The admin username to create.

jenkins_admin_password string required

The admin password to assign.

jenkins_additional_plugins list of string (default: [])

Additional Jenkins plugins to install.

jenkins_saml_keystore_path string

Path to the Java Key Store file containing the SAML2 key and certificate for the SAML plugin.

jenkins_tls_cert string required

File content for the TLS/SSL certificate to serve for your Jenkins instance.

jenkins_tls_key string required

File content for the TLS/SSL key to serve for your Jenkins instance.

jenkins_url string

The public URL where Jenkins will be available.

Configuring Jenkins

While our goal is to configure production-ready Jenkins out of the box, there are some steps that need to be configured manually after you deploy your instance.

Keeping Jenkins up to date

Jenkins is pulled from the Jenkins repos for your distro (currently we only support Ubuntu). As long as your OS is configured to update automatically, you'll always pull in the latest version of Jenkins. For Debian/Ubuntu, install unattended-upgrades.

SAML2 authentication

TODO

Email notifications

TODO

Setup a project with blue ocean

TODO

Development

Requirements:

• Docker v18
• pipenv

Install the dependencies.

$ pipenv install --dev

Run the tests.

$ pipenv run test

Accessing Jenkins

Once converged in molecule, you can access the Jenkins image locally. First, get the IP address of the docker container.

$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' jenkins-bionic

Then open your web browser to that IP on port 8080.

Contributing

See CONTRIBUTING for additional information.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.