[[PageOutline(2-5,Contents,pullout)]]
= Hudson Trac Integration Plugin (works also for Jenkins) =

== Description ==

Integrate [http://hudson-ci.org/ Hudson] or the 
actual fork [http://jenkins-ci.org/ Jenkins] build results into the Trac
timeline and (optionally) provide a navbar menu to link to the Hudson instance.

This plugin works very similar to the LuntbuildTracIntegration plugin and the
[http://dev.rectang.com/projects/continutrac Trac Continuum] plugin. The build
results are obtained from the Hudson remote API.

''Note'': as of version 0.4 this plugin requires Hudson 1.367 or later; if
you are running an earlier version of Hudson then you'll need to grab r7912
instead.

For additional integration between Trac and Jenkins see [https://wiki.jenkins-ci.org/display/JENKINS/Trac+Plugin Jenkins Trac Plugin] and [https://wiki.jenkins-ci.org/display/JENKINS/Trac+Publisher+Plugin Trac Publisher Plugin].

[[Image(hudson_plugin_screenshot.png, border=1)]]

== Configuration ==

As with all plugins, you must enable it explicitly, either via Trac's
UI (Admin -> General -> Plugins) or by directly editing the trac.ini:
{{{
[components]
hudsontrac.* = enabled
}}}

There are 11 options you can configure in your trac.ini under the
section `[hudson]` (if you have the IniAdminPlugin installed they will
show up on the Trac Admin page under `hudson`):
 job_url::
   The url of the top-level hudson page if you want to display all
   jobs in the timeline, or a job or module url if you want only
   display builds from a single job or module.
   Examples: `http://localhost/hudson/` (for builds from all jobs),
   `http://localhost/hudson/job/build_foo/` (for builds from the
   `build_foo` job only).
   The default is `http://localhost/hudson/`.
 username::
   The username to use when accessing hudson; leave empty if no
   authentication is needed. Default is empty.
 password::
   The password to use when accessing hudson; leave empty if no
   authentication is needed. Default is empty.
 display_modules::
   If set to `true` then display the builds of individual modules in
   the timeline too; otherwise only builds of jobs are displayed.
   Default is `false`.
 main_page::
   The url of the hudson page to link to from the trac mainnav; if
   empty, no entry is created in the mainnav. Example: `/hudson/`.
   The default is `/hudson/`.
 display_in_new_tab::
   If set to `true` then open the above hudson page in a new tab (or
   window) instead of in the current tab/window. Not used if
   `main_page` is not set. Default is `false`.
 alternate_success_icon::
   Display a green ball instead of the standard blue one for
   successful builds. Default is `false`.
 display_build_descriptions::
   Whether to display the build descriptions for each build instead of
   the canned "Build finished successfully" etc messages. Default is
   `true`.
 display_building::
   If `true`, builds that have started but not yet completed will also
   be displayed in the timeline.
 list_changesets::
   If set to `true` then each build entry in the timeline will also
   list all the changesets that triggered the build.
 display_culprit::
   Display the culprit(s) for each build. This is a comma-separated
   list of zero or more of the following tokens: `starter`, `author`,
   `authors`, `culprit`, `culprits`. `starter` is the user that
   started the build, if any; `author` is the author of the first
   commit, if any; `authors` is the list of authors of all commits;
   `culprit` is the first of what hudson thinks are the culprits that
   caused the build; and `culprits` is the list of all culprits. If
   this option is a list, the first non-empty value is used. Example:
   `starter,authors` (this would show who started the build if it was
   started manually, else list the authors of the commits that
   triggered the build if any, else show no author for the build).


Example trac.ini (not necessary if using the defaults):
{{{
[hudson]
job_url = http://localhost/hudson/job/build_foo/
main_page = /hudson/job/build_foo/
alternate_success_icon = true
}}}

Lastly, make sure you assign users the `BUILD_VIEW` permission in
order for them to be able to see the builds in the timeline.


== Bugs/Feature Requests == 

Existing bugs and feature requests for HudsonTracPlugin are [query:status!=closed&component=HudsonTracPlugin&order=priority here].

If you have any issues, create a 
[/newticket?component=HudsonTracPlugin&owner=roadrunner new ticket].

== Download and Source ==

Download the [download:hudsontracplugin zipped source], check out [/svn/hudsontracplugin using Subversion], or [source:hudsontracplugin browse the source] with Trac.

== Upgrade Notes ==

If you are upgrading from version 0.3 of this plugin (pre r9467) then
make sure you're running Hudson 1.367 or later.

If you are upgrading from version 0.2 of this plugin (pre r6683) then
you will need to make the following changes:
 * the `feed_url` option has been replaced by the `job_url` option;
   the latter points to the top-level hudson page or to a job page,
   not an RSS feed anymore.
 * the `display_subprojects` has been renamed `display_modules`
 * you must assign users the `BUILD_VIEW` permission in order for them
   to see the builds
 * The [http://www.feedparser.org/ python-feedparser] library is no
   longer required.

== Recent Changes ==

[[ChangeLog(hudsontracplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:roadrunner] [[BR]]
'''Maintainer:''' [wiki:roadrunner] [[BR]]
'''Contributors:'''