4.13.1.1 Buildbot Web Resources

Certain URLs are “magic”, and the pages they serve are created by code in various classes in the buildbot.status.web package instead of being read from disk. The most common way to access these pages is for the buildmaster admin to write or modify the index.html page to contain links to them. Of course other project web pages can contain links to these buildbot pages as well.

Many pages can be modified by adding query arguments to the URL. For example, a page which shows the results of the most recent build normally does this for all builders at once. But by appending “?builder=i386” to the end of the URL, the page will show only the results for the “i386” builder. When used in this way, you can add multiple “builder=” arguments to see multiple builders. Remembering that URL query arguments are separated from each other with ampersands, a URL that ends in “?builder=i386&builder=ppc” would show builds for just those two Builders.

The branch= query argument can be used on some pages. This filters the information displayed by that page down to only the builds or changes which involved the given branch. Use branch=trunk to reference the trunk: if you aren't intentionally using branches, you're probably using trunk. Multiple branch= arguments can be used to examine multiple branches at once (so appending ?branch=foo&branch=bar to the URL will show builds involving either branch). No branch= arguments means to show builds and changes for all branches.

Some pages may include the Builder name or the build number in the main part of the URL itself. For example, a page that describes Build #7 of the “i386” builder would live at /builders/i386/builds/7.

The table below lists all of the internal pages and the URLs that can be used to access them.

/waterfall

This provides a chronologically-oriented display of the activity of all builders. It is the same display used by the Waterfall display.

By adding one or more “builder=” query arguments, the Waterfall is restricted to only showing information about the given Builders. By adding one or more “branch=” query arguments, the display is restricted to showing information about the given branches. In addition, adding one or more “category=” query arguments to the URL will limit the display to Builders that were defined with one of the given categories.

A 'show_events=true' query argument causes the display to include non-Build events, like slaves attaching and detaching, as well as reconfiguration events. 'show_events=false' hides these events. The default is to show them.

By adding the 'failures_only=true' query argument, the Waterfall is restricted to only showing information about the builders that are currently failing. A builder is considered failing if the last finished build was not successful, a step in the current build(s) is failing, or if the builder is offline.

The last_time=, first_time=, and show_time= arguments will control what interval of time is displayed. The default is to show the latest events, but these can be used to look at earlier periods in history. The num_events= argument also provides a limit on the size of the displayed page.

The Waterfall has references to resources many of the other portions of the URL space: /builders for access to individual builds, /changes for access to information about source code changes, etc.

/grid

This provides a chronologically oriented display of builders, by revision. The builders are listed down the left side of the page, and the revisions are listed across the top.

By adding one ore more “category=” arguments the grid will be restricted to revisions in those categories.

A “width=N” argument will limit the number of revisions shown to N, defaulting to 5.

A “branch=BRANCHNAME” argument will limit the grid to revisions on branch BRANCHNAME.

/tgrid

The Transposed Grid is similar to the standard grid, but, as the name implies, transposes the grid: the revisions are listed down the left side of the page, and the build hosts are listed across the top. It accepts the same query arguments. The exception being that instead of “width” the argument is named “length.”

This page also has a “rev_order=” query argument that lets you change in what order revisions are shown. Valid values are “asc” (ascending, oldest revision first) and “desc” (descending, newest revision first).

/console

EXPERIMENTAL: This provides a developer-oriented display of the the last changes and how they affected the builders.

It allows a developer to quickly see the status of each builder for the first build including his or her change. A green box means that the change succeeded for all the steps for a given builder. A red box means that the changed introduced a new regression on a builder. An orange box means that at least one of the test failed, but it was also failing in the previous build, so it is not possible to see if there was any regressions from this change. Finally a yellow box means that the test is in progress.

By adding one or more “builder=” query arguments, the Console view is restricted to only showing information about the given Builders. Adding a “repository=” argument will limit display to a given repository. By adding a “branch=” query argument, the display is restricted to showing information about the given branch. In addition, adding one or more “category=” query arguments to the URL will limit the display to Builders that were defined with one of the given categories.

By adding one or more “name=” query arguments to the URL, the console view is restricted to only showing changes made by the given users.

NOTE: To use this page, your buildbot.css file in public_html must be the one found in buildbot/status/web/extended.css.

The console view is still in development. At this moment by default the view sorts revisions lexically, which can lead to odd behavior with non-integer revisions (e.g., git), or with integer revisions of different length (e.g., 999 and 1000). It also has some issues with displaying multiple braches at the same time. If you do have multiple branches, you should use the “branch=” query argument. The order_console_by_time option may help sorting revisions, although it depends on the date being set correctly in each commit:

          w = html.WebStatus(http_port=8080, order_console_by_time=True)

/rss

This provides a rss feed summarizing all failed builds. The same query-arguments used by 'waterfall' can be added to filter the feed output.

/atom

This provides an atom feed summarizing all failed builds. The same query-arguments used by 'waterfall' can be added to filter the feed output.

/json

This view provides quick access to Buildbot status information in a form that is easiliy digested from other programs, including JavaScript. See /json/help for detailed interactive documentation of the output formats for this view.

/buildstatus?builder=$BUILDERNAME&number=$BUILDNUM

This displays a waterfall-like chronologically-oriented view of all the steps for a given build number on a given builder.

/builders/$BUILDERNAME

This describes the given Builder, and provides buttons to force a build. A numbuilds= argument will control how many build lines are displayed (5 by default).

/builders/$BUILDERNAME/builds/$BUILDNUM

This describes a specific Build.

/builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME

This describes a specific BuildStep.

/builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME/logs/$LOGNAME

This provides an HTML representation of a specific logfile.

/builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME/logs/$LOGNAME/text

This returns the logfile as plain text, without any HTML coloring markup. It also removes the “headers”, which are the lines that describe what command was run and what the environment variable settings were like. This maybe be useful for saving to disk and feeding to tools like 'grep'.

/changes

This provides a brief description of the ChangeSource in use (see Change Sources).

/changes/NN

This shows detailed information about the numbered Change: who was the author, what files were changed, what revision number was represented, etc.

/buildslaves

This summarizes each BuildSlave, including which Builders are configured to use it, whether the buildslave is currently connected or not, and host information retrieved from the buildslave itself.

A “no_builders=1“ URL argument will omit the builders column. This is useful if each buildslave is assigned to a large number of builders.

/one_line_per_build

This page shows one line of text for each build, merging information from all Builders¹. Each line specifies the name of the Builder, the number of the Build, what revision it used, and a summary of the results. Successful builds are in green, while failing builds are in red. The date and time of the build are added to the right-hand edge of the line. The lines are ordered by build finish timestamp.

One or more builder= or branch= arguments can be used to restrict the list. In addition, a numbuilds= argument will control how many lines are displayed (20 by default).

/builders

This page shows a small table, with one box for each Builder, containing the results of the most recent Build. It does not show the individual steps, or the current status. This is a simple summary of buildbot status: if this page is green, then all tests are passing.

As with /one_line_per_build, this page will also honor builder= and branch= arguments.

/about

This page gives a brief summary of the Buildbot itself: software version, versions of some libraries that the Buildbot depends upon, etc. It also contains a link to the buildbot.net home page.

There are also a set of web-status resources that are intended for use by other programs, rather than humans.

/change_hook

This provides an endpoint for web-based source change notification. It is used by github and contrib/post_build_request.py. See Change Hooks for more details.