opendev/gerrit
Code Issues Proposed changes
Files
cba67502a3912fa64e72014242bade93ab75ad5b
gerrit/Documentation/config-hooks.txt
Khai Do 71b58990e9 Append approval info to every comment-added stream event and hook 
This change is driven by the RFC proposal[1] to show label
transitions more explicitly in Gerrit. Stream events only
provides label information on review events that contain
a vote transition.  When a user submits a review with only a
reply message the approvals information is not added to the
stream event and hooks. This change will make Gerrit append
approvals info to every comment-added event including the
ones that do not contain vote changes.

Since labels are shown for every event we will add an 'oldValue'
property to the approvalAttribute to distinguish when a vote
transition has occurred.  The 'oldValue' attribute contains
the previous vote score.  This attribute will only appear when
there is a vote transition.

The comment-added stream event will look like this:

  "approvals":[{"type":"Code-Review","description":"Code-Review",
  "value":"-1", "oldValue":"0"}, {"type":"Verified",
  "description":"Verified","value":"0"}],
  "comment":"Patch Set 1: Code-Review+1\n\nMy Message" ...

This change will also a '--$LabelName-oldValue' parameter to
corresponding comment-added change hook:

  hook[comment-added] output:
  --change I2cd8327360ff89338a4e7f0591bf0c037e9aa5db
  --is-draft false --change-url http://localhost:8080/201
  --change-owner John Smith (jsmith@gmail.com) --project okc
  --branch master --author John Smith (jsmith@gmail.com)
  --commit 55079187f7ce1c461de804c13f2dd71d64a85280
  --comment Patch Set 1: Code-Review-1 --Code-Review -1
  --Code-Review-oldValue 0 --Verified 0

[1] https://groups.google.com/d/msg/repo-discuss/soqmGjRpl-4/IIfAF4jbCQAJ

Bug: Issue 3220
Change-Id: Ibc1c64d70e790c7b507db79931f31fd77f25e276
2016-03-18 14:47:36 +01:00

195 lines
6.7 KiB
Plaintext
Raw Blame History

= Gerrit Code Review - Hooks
Gerrit does not run any of the standard git hooks in the
repositories it works with, but it does have its own hook mechanism
included. Gerrit looks in `'$site_path'/hooks` for executables with
names listed below.
The environment will have GIT_DIR set to the full path of the
affected git repository so that git commands can be easily run.
Make sure your hook scripts are executable if running on *nix.
With the exception of the ref-update hook, hooks are run in the background
after the relevant change has taken place so are unable to affect
the outcome of any given change. Because of the fact the hooks are
run in the background after the activity, a hook might not be notified
about an event if the server is shutdown before the hook can be invoked.
== Supported Hooks
=== ref-update
This is called when a push request is received by Gerrit. It allows
a push to be rejected before it is committed to the Gerrit repository.
If the script exits with non-zero return code the push will be rejected.
Any output from the script will be returned to the user, regardless of the
return code.
This hook is called synchronously so it is recommended that
it not block. A default timeout on the hook is set to 30 seconds to avoid
"runaway" hooks using up server threads. See link:config-gerrit.html#hooks.syncHookTimeout[hooks.syncHookTimeout]
for configuration details.
====
ref-update --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1>
====
=== patchset-created
This is called whenever a patchset is created (this includes new
changes and drafts).
====
patchset-created --change <change id> --is-draft <boolean> --kind <change kind> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
====
kind:: change kind represents the kind of change uploaded, also represented in link:json.html#patchSet[patchSet]
REWORK;; Nontrivial content changes.
TRIVIAL_REBASE;; Conflict-free merge between the new parent and the prior patch set.
NO_CODE_CHANGE;; No code changed; same tree and same parent tree.
NO_CHANGE;; No changes; same commit message, same tree and same parent tree.
=== draft-published
This is called whenever a draft change is published.
====
draft-published --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
====
=== comment-added
This is called whenever a comment is added to a change.
====
comment-added --change <change id> --is-draft <boolean> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --author <comment author> --commit <commit> --comment <comment> [--<approval category id> <score> --<approval category id> <score> --<approval category id>-oldValue <score> ...]
====
=== change-merged
Called whenever a change has been merged.
====
change-merged --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --newrev <sha1>
====
=== merge-failed
Called whenever a change has failed to merge.
====
merge-failed --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --reason <reason>
====
=== change-abandoned
Called whenever a change has been abandoned.
====
change-abandoned --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --abandoner <abandoner> --commit <sha1> --reason <reason>
====
=== change-restored
Called whenever a change has been restored.
====
change-restored --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --restorer <restorer> --commit <sha1> --reason <reason>
====
=== ref-updated
Called whenever a ref has been updated.
====
ref-updated --oldrev <old rev> --newrev <new rev> --refname <ref name> --project <project name> --submitter <submitter>
====
=== project-created
Called whenever a project has been created.
====
project-created --project <project name> --head <head name>
====
=== reviewer-added
Called whenever a reviewer is added to a change.
====
reviewer-added --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --reviewer <reviewer>
====
=== topic-changed
Called whenever a change's topic is changed from the Web UI or via the REST API.
====
topic-changed --change <change id> --change-owner <change owner> --project <project name> --branch <branch> --changer <changer> --old-topic <old topic> --new-topic <new topic>
====
=== hashtags-changed
Called whenever hashtags are added to or removed from a change from the Web UI
or via the REST API.
====
hashtags-changed --change <change id> --change-owner <change owner> --project <project name> --branch <branch> --editor <editor> --added <hashtag> --removed <hashtag> --hashtag <hashtag>
====
The `--added` parameter may be passed multiple times, once for each
hashtag that was added to the change.
The `--removed` parameter may be passed multiple times, once for each
hashtag that was removed from the change.
The `--hashtag` parameter may be passed multiple times, once for each
hashtag remaining on the change after the add or remove operation has
been performed.
=== cla-signed
Called whenever a user signs a contributor license agreement.
====
cla-signed --submitter <submitter> --user-id <user_id> --cla-id <cla_id>
====
== Configuration Settings
It is possible to change where Gerrit looks for hooks, and what
filenames it looks for, by adding a [hooks] section in gerrit.config.
Gerrit will use the value of hooks.path for the hooks directory.
For the hook filenames, Gerrit will use the values of hooks.patchsetCreatedHook,
hooks.draftPublishedHook, hooks.commentAddedHook, hooks.changeMergedHook,
hooks.changeAbandonedHook, hooks.changeRestoredHook, hooks.refUpdatedHook,
hooks.refUpdateHook, hooks.reviewerAddedHook and hooks.claSignedHook.
== Missing Change URLs
If link:config-gerrit.html#gerrit.canonicalWebUrl[gerrit.canonicalWebUrl]
is not set in `gerrit.config` the `--change-url` flag may not be
passed to all hooks. Hooks started out of an SSH context (for example
the patchset-created hook) don't know the server's web URL, unless
this variable is configured.
== SEE ALSO
* link:config-gerrit.html#hooks[Section hooks]
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink