ansible-jenkins-php-v1/README.md

**Important : this playbook is quick'n dirty and work in progress. Carefully review before using it.**

This Ansible playbook aims at setting a Jenkins CI host linked to Gitea repositories. It will :
- install jenkins from pkg.jenkins.io
- install the default JDK
- install the Jenkins plugins requested for the jenkins-php.org templates
- create a jenkins user `gitea` with restricted access just to launch a job
- creates the specified jobs
- install NginX and set up 2 vhost as recommended in https://wiki.jenkins.io/display/JENKINS/Configuring+Content+Security+Policy

Most of the configuration should be available in the inventory.

It is launched usually like this : `ansible-playbook site.yml`

## Prerequisites

### Prerequisites for the Jenkins hosts
Hosts should be accessible via SSH as the root user (else, add the usual
`remote_user`/`become` instructions in ansible.cfg) and with the Python
prerequisite of Ansible (usually `python-minimal`).

Only tested on Debian 10 amd64 so far, with Ansible 2.7.7.

Note : to test or to limit to one particular host :
```
ansible foo.bar.com -m ping
ansible-playbook -l foo.bar.com -v -C -D site.yml
```

### Prerequisites for the repositories
None at the moment : this playbook will not configure Gitea or anything
else outside Jenkins. The webhooks and the access to allow Jenkins to
clone/pull the repositories are to be done manually (a recap will be
displayed at the end of the playbook).

### Prerequisites for the projects
Nothing mandatory except the [`build.xml`](http://jenkins-php.org/automation.html)
file at the root of each project.

See examples in the `roles/jenkins-php-v1/files/skeletons/` directory.

## Directory layout

We follow (more or less) the recommendations of 
https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html
with :
- `site.yml` : master playbook
- `ansible.cfg` and `inventory` : the first one set up some default configurations and introduce the second one : the inventory.
- `roles/common/`, `roles/fooapp/` : the roles with their tree `tasks/main.yml`, `files/`, `handlers/main.yml`, ...
- `group_vars/group1.yml` and `host_vars/hostname1.yml` : variables dedicated to a group or a host respectively.

Note : contrary to some recommendations, I prefer to set some variables in
the inventory instead of `host_vars` and `group_vars`. For a small playbook
like this one, it seems acceptable and it makes it easier to look where to
adapt.

## TODO

- stop execution if host is running an untested system ?
- use jenkins-cli to maintain credentials.xml ? It's not really easy to manipulate in Ansible at the moment...
- lookup more throroughfully at [configuration as code plugin](https://plugins.jenkins.io/configuration-as-code/)
- update plugins, or at least display a warning when they are not up to date.
- integrate docker-plugin nicely

## License

[CC-BY-SA 3.0](http://creativecommons.org/licenses/by-sa/3.0/) like http://jenkins-php.org/ by [Sebastian Bergmann](http://sebastian-bergmann.de/) and his contributors.