Differential D25007 Diff 23 src/docs/user/userguide/harbormaster.diviner

Changeset View

Standalone View

src/docs/user/userguide/harbormaster.diviner

@title Harbormaster User Guide		@title Harbormaster User Guide
@group userguide		@group userguide

Guide to Harbormaster, a build and continuous integration application.		Guide to Harbormaster, a build and continuous integration application.

Overview		Overview
========		========

WARNING: Harbormaster is still very rough. Read this document carefully to		WARNING: Harbormaster is still very rough. Read this document carefully to
understand what it can and can not do and what to expect in the future.		understand what it can and can not do and what to expect in the future.

The Harbormaster application provides build and continuous integration support		The Harbormaster application provides build and continuous integration support
for Phabricator.		for Phorge.

Harbormaster is not a mature application. You should expect it to have major		Harbormaster is not a mature application. You should expect it to have major
missing capabilities and to change substantially over time. The current version		missing capabilities and to change substantially over time. The current version
of Harbormaster can perform some basic build tasks, but has many limitations		of Harbormaster can perform some basic build tasks, but has many limitations
and is not a complete build platform.		and is not a complete build platform.

In particular, you should be aware of these common limitations:		In particular, you should be aware of these common limitations:

▲ Show 20 Lines • Show All 68 Lines • ▼ Show 20 Lines
can use to make a call to an external build system like Jenkins. Today, most		can use to make a call to an external build system like Jenkins. Today, most
plans should therefore look something like this:		plans should therefore look something like this:

- Use a "Make HTTP Request" step to tell Jenkins or some other similar		- Use a "Make HTTP Request" step to tell Jenkins or some other similar
external build system about the code.		external build system about the code.
- Have the build step "Wait for Message" after the external system is		- Have the build step "Wait for Message" after the external system is
notified.		notified.
- Write custom code on the build server to respond to the request, run a		- Write custom code on the build server to respond to the request, run a
build, then report the results back to Phabricator by calling the		build, then report the results back to Phorge by calling the
`harbormaster.sendmessage` Conduit API.		`harbormaster.sendmessage` Conduit API.

You'll need to write a nontrivial amount of code to get this working today.		You'll need to write a nontrivial amount of code to get this working today.
In the future, Harbormaster will become more powerful and have more builtin		In the future, Harbormaster will become more powerful and have more builtin
support for interacting with build systems.		support for interacting with build systems.


Triggering Builds		Triggering Builds
Show All 37 Lines

With staging areas, `arc` pushes a copy of the local changes somewhere as a		With staging areas, `arc` pushes a copy of the local changes somewhere as a
side effect of running `arc diff`. In Git, it pushes changes to a tag like		side effect of running `arc diff`. In Git, it pushes changes to a tag like
`phabricator/diff/123` in a designated remote.		`phabricator/diff/123` in a designated remote.

The build system can then interact with this copy using normal VCS commands.		The build system can then interact with this copy using normal VCS commands.
This is simpler to configure, use, troubleshoot and work with than `arc patch`.		This is simpler to configure, use, troubleshoot and work with than `arc patch`.

With `arc patch`, the build system downloads patches from Phabricator and		With `arc patch`, the build system downloads patches from Phorge and
applies them to a local working copy. This is more complex and more error-prone		applies them to a local working copy. This is more complex and more error-prone
than staging areas.		than staging areas.

Automatic Staging Areas: This is the recommended mechanism for change		Automatic Staging Areas: This is the recommended mechanism for change
handoff. This mechanism has not been built yet, so you can not use it.		handoff. This mechanism has not been built yet, so you can not use it.

Manual Staging Areas: If you can not use automatic staging areas, manual		Manual Staging Areas: If you can not use automatic staging areas, manual
staging areas are the next best approach. Manual staging areas are only		staging areas are the next best approach. Manual staging areas are only
Show All 35 Lines	There are several ways to select a staging area:
- Using automatic staging areas avoids all this complexity by using the		- Using automatic staging areas avoids all this complexity by using the
repository as its own staging area but hiding the tags from users.		repository as its own staging area but hiding the tags from users.

Once you've configured a staging area, have your build system clone the staging		Once you've configured a staging area, have your build system clone the staging
area repository and do a checkout of the relevant tag in order to perform a		area repository and do a checkout of the relevant tag in order to perform a
build.		build.

`arc patch`: You can also have the build system pull changes out of		`arc patch`: You can also have the build system pull changes out of
Phabricator as patches and apply them with `arc patch`. This mechanism is the		Phorge as patches and apply them with `arc patch`. This mechanism is the
most complex to configure and debug, and is much less reliable than using		most complex to configure and debug, and is much less reliable than using
staging areas. It is not recommended.		staging areas. It is not recommended.

To use `arc patch`-based handoff, install PHP on your build server and set up		To use `arc patch`-based handoff, install PHP on your build server and set up
`arc`. Create a "bot" user for your build system and generate a Conduit token		`arc`. Create a "bot" user for your build system and generate a Conduit token
in {nav Settings > Conduit API Tokens}. Then have your build system clone the		in {nav Settings > Conduit API Tokens}. Then have your build system clone the
repository and run `arc patch` to apply the changes:		repository and run `arc patch` to apply the changes:

$ arc patch --conduit-token <token> --diff <diff-id>		$ arc patch --conduit-token <token> --diff <diff-id>

This will usually work, but is more complex and less reliable than using a		This will usually work, but is more complex and less reliable than using a
staging area.		staging area.


Troubleshooting		Troubleshooting
===============		===============

You can troubleshoot Harbormaster by using `bin/harbormaster` from the command		You can troubleshoot Harbormaster by using `bin/harbormaster` from the command
line. Run it as `bin/harbormaster help` for details.		line. Run it as `bin/harbormaster help` for details.

In particular, you can run manual builds in the foreground from the CLI to see		In particular, you can run manual builds in the foreground from the CLI to see
more details about what they're doing:		more details about what they're doing:

phabricator/ $ ./bin/harbormaster build D123 --plan 456 --trace		phorge/ $ ./bin/harbormaster build D123 --plan 456 --trace

This may help you understand or debug issues with a build plan.		This may help you understand or debug issues with a build plan.