[[PageOutline(2-5,Contents,pullout)]]

= Hudson and Jenkins integration into Trac

== Description

[[Image(hudson_logo.png, align=right)]]
[[Image(jenkins_logo.png, align=right)]]

This plugin integrates [https://jenkins-ci.org/ Jenkins] (or the discontinued Hudson) build results into the Trac timeline and (optionally) provides a navbar menu to link to the Jenkins instance.

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 Jenkins Trac Publisher Plugin].

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

NOTE: For compatibility reasons the Plugin is named HudsonTracPlugin and not JenkinsTracPlugin and the config section is hudson and not jenkins.

== Bugs/Feature Requests

Existing bugs and feature requests for HudsonTracPlugin are 
[report:9?COMPONENT=HudsonTracPlugin here].

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

[[TicketQuery(component=HudsonTracPlugin,group=type,format=progress)]]

== Download

Download the zipped source from [export:hudsontracplugin here].

== Source

Check out HudsonTracPlugin from [/svn/hudsontracplugin here] using Subversion, or [source:hudsontracplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

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

== Configuration

There are the following options you can configure in your `trac.ini` file 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 Jenkins 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/jenkins/` (for builds from all jobs),
   `http://localhost/jenkins/job/build_foo/` (for builds from the
   `build_foo` job only).
   The default is `http://localhost/jenkins/`.
 api_path::
   The path part of the API, either "api/python" or "api/json".
   The default is `api/json`.
 interfacename::
   The interfacename (i.e. Jenkins) to use.
   The default is `Jenkins`.
 nav_label::
   The label for the nav menu entry (default value will be translated).
   The default is `Builds`.
 username::
   The username to use when accessing Jenkins; leave empty if no
   authentication is needed. Default is empty.
 password::
   The password to use when accessing Jenkins; leave empty if no
   authentication is needed. Default is empty.
 api_token::
   The API Token to use to access Jenkins. This takes precedence over
   any password and is the preferred mechanism if you are running
   Jenkins 1.426 or later and Jenkins is enforcing authentication (as
   opposed to, for example, a proxy in front of Jenkins).
 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 Jenkins page to link to from the trac mainnav; if
   empty, no entry is created in the mainnav. Example: `/jenkins/`.
   The default is `/jenkins/`.
 timeline_opt_label::
   The label to use for the above link, can contain %(interfacename) to be replaced by the interface name option.
   The default is `%(interfacename)s Builds`.
 display_in_new_tab::
   If set to `true` then open the above Jenkins 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 Jenkins 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`:
{{{#!ini
[hudson]
job_url = http://localhost/jenkins/job/build_foo/
main_page = /jenkins/job/build_foo/
alternate_success_icon = true
}}}

Note that it is not necessary to specify this `hudson` section if you are using the default values.

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

== Recent Changes

[[ChangeLog(hudsontracplugin, 3)]]

== Author/Contributors

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