The most common way to run a WebStatus
is on a regular TCP
port. To do this, just pass in the TCP port number when you create the
WebStatus
instance; this is called the http_port
argument:
from buildbot.status.html import WebStatus c['status'].append(http_port=WebStatus(http_port=8080))
The http_port
argument is actually a “strports specification” for the
port that the web server should listen on. This can be a simple port number, or
a string like http_port="tcp:8080:interface=127.0.0.1"
(to limit
connections to the loopback interface, and therefore to clients running on the
same host)1.
If instead (or in addition) you provide the distrib_port
argument, a twisted.web distributed server will be started either on a
TCP port (if distrib_port
is like "tcp:12345"
) or more
likely on a UNIX socket (if distrib_port
is like
"unix:/path/to/socket"
).
The public_html
option gives the path to a regular directory of HTML
files that will be displayed alongside the various built-in URLs buildbot
supplies. This is most often used to supply CSS files (/buildbot.css
)
and a top-level navigational file (/index.html
), but can also serve any
other files required - even build results!
The buildbot web status is, by default, read-only. It displays lots of information, but users are not allowed to affect the operation of the buildmaster. However, there are a number of supported activities that can be enabled, and Buildbot can also perform rudimentary username/password authentication. The actions are:
forceBuild
forceAllBuilds
pingBuilder
gracefulShutdown
stopBuild
stopAllBuilds
cancelPendingBuild
cleanShutdown
For each of these actions, you can configure buildbot to never allow the action, always allow the action, allow the action to any authenticated user, or check with a function of your creation to determine whether the action is OK.
This is all configured with the Authz
class:
from buildbot.status.html import WebStatus from buildbot.status.web.authz import Authz authz = Authz( forceBuild=True, stopBuild=True) c['status'].append(http_port=WebStatus(http_port=8080, authz=authz))
Each of the actions listed above is an option to Authz
. You can specify
False
(the default) to prohibit that action or True
to enable it.
If you do not wish to allow strangers to perform actions, but do want
developers to have such access, you will need to add some authentication
support. Pass an instance of status.web.auth.IAuth
as a auth
keyword argument to Authz
, and specify the action as "auth"
.
from buildbot.status.html import WebStatus from buildbot.status.web.authz import Authz from buildbot.status.web.auth import BasicAuth users = [('bob', 'secret-pass'), ('jill', 'super-pass')] authz = Authz(auth=BasicAuth(users), forceBuild='auth', # only authenticated users pingBuilder=True, # but anyone can do this ) c['status'].append(WebStatus(http_port=8080, authz=authz)) # or from buildbot.status.web.auth import HTPasswdAuth auth = (HTPasswdAuth('/path/to/htpasswd'))
The class BasicAuth
implements a basic authentication mechanism using a
list of user/password tuples provided from the configuration file. The class
HTPasswdAuth
implements an authentication against an .htpasswd
file.
If you need still-more flexibility, pass a function for the authentication action. That function will be called with an authenticated username and some action-specific arguments, and should return true if the action is authorized.
def canForceBuild(username, builder_status): if builder_status.getName() == 'smoketest': return True # any authenticated user can run smoketest elif username == 'releng': return True # releng can force whatever they want else: return False # otherwise, no way. authz = Authz(auth=BasicAuth(users), forceBuild=canForceBuild)
The forceBuild
and pingBuilder
actions both supply a
BuilderStatus object. The stopBuild
action supplies a BuildStatus
object. The cancelPendingBuild
action supplies a BuildRequest. The
remainder do not supply any extra arguments.
The WebStatus uses a separate log file (http.log) to avoid clutter buildbot's default log (twistd.log) with request/response messages. This log is also, by default, rotated in the same way as the twistd.log file, but you can also customize the rotation logic with the following parameters if you need a different behaviour.
An integer defining the file size at which log files are rotated.
The maximum number of old log files to keep.
These arguments adds an URL link to various places in the WebStatus, such as revisions, repositories, projects and, optionally, ticket/bug references in change comments.
The revlink
is similarly used to create links from revision
ids to a web-view of your source control system. This will either be
a string, a dict from string (repository ids) to strings, or a callable.
The string should use '%s' to insert
the revision id in the url. I.e. for Buildbot on github:
revlink='http://github.com/djmitche/buildbot/tree/%s'
(The revision id will be URL encoded before inserted in the replacement string)
The callable takes the revision id and repository argument, and should return an URL to the revision.
The changecommentlink
argument can be used to create links to
ticket-ids from change comments (i.e. #123).
The argument can either be a tuple of three strings, a dictionary mapping
strings (project names) to tuples or a callable taking a changetext
(a jinja2.Markup
instance) and a project name, returning a the
same change text with additional links/html tags added to it.
If the tuple is used, it should contain three strings where the first
element is a regex that
searches for strings (with match groups), the second is a replace-string
that, when substituted with \1 etc, yields the URL and the third
is the title attribute of the link.
(The <a href="" title=""></a>
is added by the system.)
So, for Trac tickets (#42, etc):
changecommentlink(r"#(\d+)", r"http://buildbot.net/trac/ticket/\1", r"Ticket \g<0>")
.
A dictionary from strings to strings, mapping project names to URLs, or a callable taking a project name and returning an URL.
Same as the projects arg above, a dict or callable mapping project names to URLs.
The order_console_by_time
option affects the rendering of the console;
see the description of the console above.
The numbuilds
option determines the number of builds that most status
displays will show. It can usually be overriden in the URL, e.g.,
?numbuilds=13
.
The num_events
option gives the default number of events that the
waterfall will display. The num_events_max
gives the maximum number of
events displayed, even if the web browser requests more.
[1] It may even be possible to provide SSL access by using a
specification like "ssl:12345:privateKey=mykey.pen:certKey=cert.pem"
,
but this is completely untested