:title: Howto

Howto
=====

Here are some instructions for accomplishing specific tasks with
Cogate.  Please let us know if you have ideas you would like to see
covered here.

Build Images with Cross-Repo-Dependencies
-----------------------------------------

Cogate makes working with mulitple repositories a cinch.  If you build
one image from one repository, setting that up with Cogate is pretty
obvious.  Even building multiple images from a single repo is
straightforward (just add more :attr:`image` stanzas).

If you build a single image from multiple git repos, Cogate has that
covered too.  You can even include multiple changes in a single image
build by specifying cross-repo-dependencies.  Cogate will check out
the change for the current pull request and any dependent changes for
other repos when it performs its image build.

By default Cogate runs the image build in the root of the checkout out
git repo where the image is defined, and the container build context
defaults to that location as well.  If you want to include more than
one repo, we need to tell Cogate to include both in the build context.

For example, let's say you have an image named `example/web-server`.
Within the `web-server` image, you include not only the source code
for the web server (the current git repo) but you also need a git repo
called `example/library`.  To set that up in Cogate, make a
``cogate.yaml`` file in the `example/web-server` repo that looks like
this:

.. code-block:: yaml

   - image:
       registry: docker.io
       repository: example/web-server
       required-projects:
         - example/library
       context: ~/src
       file: ~/src/github.com/example/web-server/Dockerfile

The :attr:`image.required-projects` attribute tells Cogate to check
out the `example/library` git repo, and the :attr:`image.context`
attribute says to include the entire source tree in the build context.
The :attr:`image.file` attribute specifies which file to use to build
that image.

The Dockerfile can reference any file in the context using
golang-style paths when building the image.