9ed2be3098
The goal is to re-orient the documentation as an introduction for new contributors and a reference for all contributors. Change-Id: I8702a5ace908c7618a6451bbfef7fc79b07429ff Reviewed-on: https://review.openstack.org/30515 Reviewed-by: Elizabeth Krumbach Joseph <lyz@princessleia.com> Reviewed-by: Clark Boylan <clark.boylan@gmail.com> Approved: Monty Taylor <mordred@inaugust.com> Reviewed-by: Monty Taylor <mordred@inaugust.com> Tested-by: Jenkins
205 lines
6.9 KiB
ReStructuredText
205 lines
6.9 KiB
ReStructuredText
:title: Jeepyb
|
|
|
|
.. _jeepyb:
|
|
|
|
Jeepyb
|
|
######
|
|
|
|
Jeepyb is a collection of tools which make managing Gerrit easier.
|
|
Specifically, management of Gerrit projects and their associated
|
|
upstream integration with things like Github and Launchpad.
|
|
|
|
At a Glance
|
|
===========
|
|
|
|
:Hosts:
|
|
* http://review.openstack.org
|
|
* http://review-dev.openstack.org
|
|
:Puppet:
|
|
* :file:`modules/jeepyb`
|
|
* :file:`modules/openstack_project/manifests/review.pp`
|
|
* :file:`modules/openstack_project/manifests/review_dev.pp`
|
|
:Configuration:
|
|
* :file:`modules/openstack_project/templates/review.projects.yaml.erb`
|
|
* :file:`modules/openstack_project/files/pypi-mirror.yaml`
|
|
:Projects:
|
|
* http://github.com/openstack-infra/jeepyb
|
|
:Bugs:
|
|
* http://bugs.launchpad.net/openstack-ci
|
|
|
|
|
|
Gerrit Project Configuration
|
|
============================
|
|
|
|
The ``manage-projects`` command in Jeepyb is able to create a new
|
|
project in Gerrit, create the new project on Github, create a local
|
|
git replica on the Gerrit host, configure the project Access Controls,
|
|
and create new groups in Gerrit.
|
|
|
|
OpenStack Gerrit projects are configured in the
|
|
:file:`modules/openstack_project/templates/review.projects.yaml.erb`.
|
|
file. When this file is updated, ``manage-projects`` is run
|
|
automatically. This file contains two sections, the first is a set of
|
|
default config values that each project can override, and the second
|
|
is a list of projects (each may contain their own overrides).
|
|
|
|
#. Config default values::
|
|
|
|
- homepage: http://example.org
|
|
local-git-dir: /var/lib/git
|
|
gerrit-host: review.example.org
|
|
gerrit-user: example-project-creator
|
|
gerrit-key: /home/gerrit2/.ssh/example_project_id_rsa
|
|
github-config: /etc/github/github-projects.secure.config
|
|
has-wiki: False
|
|
has-issues: False
|
|
has-pull-requests: False
|
|
has-downloads: False
|
|
|
|
#. Project definition::
|
|
|
|
- project: example/gerrit
|
|
description: Fork of Gerrit used by Example
|
|
remote: https://gerrit.googlesource.com/gerrit
|
|
- project: example/project1
|
|
description: Best project ever.
|
|
has-wiki: True
|
|
acl-config: /path/to/acl/file
|
|
|
|
The above config gives puppet and its related scripts enough information
|
|
to create new projects, but not enough to add access controls to each
|
|
project. To add access control you need to have have an ``acl-config``
|
|
option for the project in ``review.projects.yaml.erb`` file. That option
|
|
should have a value that is a path to the ``project.config`` for that
|
|
project.
|
|
|
|
That is the high level view of how we can configure projects using the
|
|
pupppet repository. To create an actual change that does all of this for
|
|
a single project you will want to do the following:
|
|
|
|
#. Add a
|
|
``modules/openstack_project/files/gerrit/acls/project-name.config``
|
|
file to the repo. The contents will probably end up looking like
|
|
the block below (note that the sections are in alphabetical order
|
|
and each indentation is 8 spaces)::
|
|
|
|
[access "refs/heads/*"]
|
|
label-Code-Review = -2..+2 group project-name-core
|
|
label-Approved = +0..+1 group project-name-core
|
|
workInProgress = group project-name-core
|
|
[access "refs/heads/milestone-proposed"]
|
|
label-Code-Review = -2..+2 group project-name-milestone
|
|
label-Approved = +0..+1 group project-name-milestone
|
|
[project]
|
|
state = active
|
|
[receive]
|
|
requireChangeId = true
|
|
requireContributorAgreement = true
|
|
[submit]
|
|
mergeContent = true
|
|
|
|
#. Add a project entry for the project in
|
|
``modules/openstack_project/templates/review.projects.yaml.erb``.::
|
|
|
|
- project: openstack/project-name
|
|
acl-config: /home/gerrit2/acls/project-name.config
|
|
|
|
#. If there is an existing repo that is being replaced by this new
|
|
project you can set the upstream value for the project. When an
|
|
upstream is set, that upstream will be cloned and pushed into Gerrit
|
|
instead of an empty repository. eg::
|
|
|
|
- project: openstack/project-name
|
|
acl-config: /home/gerrit2/acls/project-name.config
|
|
upstream: git://github.com/awesumsauce/project-name.git
|
|
|
|
That is all you need to do. Push the change to gerrit and if necessary
|
|
modify group membership for the groups you configured in the
|
|
``project.config`` through Launchpad.
|
|
|
|
Commit Hooks
|
|
============
|
|
|
|
Launchpad Bug Integration
|
|
-------------------------
|
|
|
|
The ``update-bug`` Jeepyb command is installed as a Gerrit commit hook
|
|
so that it runs each time a patchset is created. It updates Launchpad
|
|
bugs based on information that it finds in the commit message. It
|
|
also contains a manual mapping of Gerrit to Launchpad project names
|
|
for projects that use a different Launchpad project for their bugs.
|
|
|
|
Launchpad Blueprint Integration
|
|
-------------------------------
|
|
|
|
The ``update-blueprint`` Jeepyb command is installed as a Gerrit
|
|
commit hook so that it runs each time a patchset is created. It
|
|
updates Launchpad blueprints based on information that it finds in the
|
|
commit message.
|
|
|
|
Impact Notification
|
|
-------------------
|
|
|
|
The ``notify-impact`` commit hook runs when new patchsets are created
|
|
and sends email notifications when certain regular expressions are
|
|
matched, such as:
|
|
|
|
* DocImpact
|
|
* SecurityImpact
|
|
|
|
Trivial Rebase Hook
|
|
-------------------
|
|
|
|
The ``trivial-rebase`` commit hook runs when new patchsets are
|
|
uploaded and detects whether the new patchset is merely a rebase onto
|
|
a new parent, or is a substantial change. If it is a rebase, it
|
|
restores previous review votes and leaves a comment in Gerrit. It
|
|
uses Gerrit's own SSH host key as the private key for access in order
|
|
to gain the "superuser" permissions needed to impersonate other users
|
|
in reviews.
|
|
|
|
|
|
Periodic Tasks
|
|
==============
|
|
|
|
Closing Github Pull Requests
|
|
----------------------------
|
|
|
|
The ``close-pull-requests`` Jeepyb command is installed as a cron job
|
|
and periodically closes all pull requests for projects so configured
|
|
in projects.yaml.
|
|
|
|
|
|
Expiring Old Reviews
|
|
--------------------
|
|
|
|
The ``expire-old-reviews`` Jeepyb command is installed as a cron job
|
|
that periodically marks reviews that have seen little activity as
|
|
`Abandoned`. Their owners may use the Gerrit interface to restore
|
|
them when they are ready for further review.
|
|
|
|
Fetching Remotes
|
|
----------------
|
|
|
|
Some projects may have remotes defined in Jeepyb; the
|
|
``fetch-remotes`` cron job will update these remotes so that their
|
|
commits are available in Gerrit.
|
|
|
|
RSS feeds
|
|
---------
|
|
|
|
Jeepyb's ``openstackwatch`` command publishes RSS feeds of Gerrit
|
|
projects.
|
|
|
|
Pypi Mirror
|
|
-----------
|
|
|
|
The ``run-mirror`` command builds a full Pypi mirror for a project or
|
|
set of projects by reading a requirements.txt file, installing all
|
|
listed dependencies into a virtualenv, inspecting the resulting
|
|
installed package set, and then downloading all of the second-level
|
|
(and further) dependencies. Essentially, the mirror is built by
|
|
introspection and contains the full set of depedencies needed whether
|
|
they are explicitly listed or not.
|
|
|