Add Gerrit CI instructions for the Gerrit maintainer
Inform the Gerrit maintainers on the Gerrit CI use and security
policies.
Also, document the way to update the Gerrit CI jobs on new
commits merged onto its master branch.
Release-Notes: Document the use of Gerrit-CI by the contributors and maintainers
Change-Id: I52cf9a749ed32205c53d9841d2d21b2fdf9dc5b5
diff --git a/Documentation/dev-ci.txt b/Documentation/dev-ci.txt
new file mode 100644
index 0000000..c5a36a2
--- /dev/null
+++ b/Documentation/dev-ci.txt
@@ -0,0 +1,61 @@
+:linkattrs:
+= Gerrit Code Review - Continuous Integration
+
+[[summary]]
+== TL;DR
+
+All the Gerrit incoming changes and stable branches are built on the
+link:https://gerrit-ci.gerritforge.com[Gerrit CI].
+
+The link:https://gerrit.googlesource.com/gerrit-ci-scripts[gerrit-ci-scripts]
+project contains all the YAML files definitions associated with the
+link:https://docs.openstack.org/infra/jenkins-job-builder/attic/[Jenkins Job Builder]
+definition of the continuous integration Jobs.
+
+Gerrit maintainers are responsible for making sure that the CI jobs are
+up-to-date by triggering the
+link:https://gerrit-ci.gerritforge.com/job/gerrit-ci-scripts/[Gerrit-CI scripts job]
+upon new commits to the master branch of the gerrit-ci-scripts project.
+
+[[sign-up]]
+== Signing up as maintainer on Gerrit-CI
+
+The link:https://gerrit-ci.gerritforge.com/job/gerrit-ci-scripts/[Gerrit-CI]
+controller allows the Gerrit maintainers to sign-in using their GitHub
+accounts and have their username defined in the list of Users.
+
+*****
+NOTE: Because of recent link:https://docs.google.com/document/d/1vDjunjDrLYYpVoVON-B_c83f56Nhm-lMDMjXmYmFYk4[security issues]
+ found on Jenkins and future potential risks, only the Gerrit
+ maintainers and contributors are allowed to access the Jenkins UI and
+ sign-up for creating an account.
+*****
+
+Once the sign-up phase is complete, the maintainer needs to grant
+himself permissions on Jenkins by creating a change to add their names into
+the Jenkins
+link:https://gerrit.googlesource.com/gerrit-ci-scripts/+/refs/heads/master/jenkins-docker/server/config-external.xml#11[config.xml]
+in the permissions XML Section.
+
+== Applying changes to Jenkins on Gerrit-CI
+
+The Jenkins setup link:https://gerrit-ci.gerritforge.com[Gerrit-CI] adopts
+a link:https://www.ncsc.gov.uk/collection/zero-trust-architecture[Zero-Trust-Architecture]
+and therefore assumes that any access could be potentially malicious.
+
+- To limit the impact of future attacks or zero-days vulnerabilities the controller
+ must not have any meaningful secret or key which could be stolen.
+- It must not be possible for anyone to change anything on the Gerrit-CI
+ infrastructure without authenticating with their credentials.
+- No credentials should be stored anywhere on the Jenkins controller.
+- Everything should be coming from the link:https://gerrit.googlesource.com/gerrit-ci-scripts[gerrit-ci-scripts] project
+ and the infrastructure must be immutable and ephemeral.
+
+Gerrit maintainers can apply the latest changes on the Jenkins controller on Gerrit-CI by performing the following
+actions:
+
+- Generate a personal API account token by authenticating to
+ link:https://gerrit-ci.gerritforge.com/user/lucamilanesio/configure[Gerrit CI user's settings]
+ and generating a new API token.
+- Trigger the link:https://gerrit-ci.gerritforge.com/job/gerrit-ci-scripts/build?delay=0sec[gerrit-ci-scripts] job
+ entering their GitHub username and their API account token
diff --git a/Documentation/dev-community.txt b/Documentation/dev-community.txt
index 07e3a11..f26ca0d 100644
--- a/Documentation/dev-community.txt
+++ b/Documentation/dev-community.txt
@@ -58,6 +58,7 @@
[[maintainer]]
== Maintainer
+* link:dev-ci.html[Gerrit CI]
* link:dev-release.html[Making a Gerrit Release]
* link:dev-release-subproject.html[Making a Release of a Gerrit Subproject]
* link:https://www.gerritcodereview.com/publishing.html[Publish Gerrit Homepage]
