Bossman works on top of git working copies. Within a git working copy, Bossman will manage resources using plugins according to a simple configuration file.

This page describes how to configure and operate bossman.


Configuration tells bossman where resources are in the repository, and which plugin to use to manage them.

It lives in a YAML file which is optional if the defaults are acceptable.

It should be called .bossman and reside at the root of the repository. It should be added to source control.

It should have a single resources field defining associations between file match patterns and resource plugins:

- module:
  pattern: akamai/property/{name}

The module field must be an importable module on the python path. Multiple resources may reference the same module.

The pattern field is a path, relative to the root of the repository. {placeholders} like {name} in the example above will always match a single path component (no slashes). The supported placeholders are specific to each plugin.

In addition to the module and pattern fields, each resouce group can define additional plugin-specific parameters in an options field.

See the Plugins documentation pages for details.


Bossman creates a .bossmancache file at the root of the repository containing cache entries to speed up specific lookups. This should be added to .gitignore.

Targeting resources

The glob argument is accepted by all bossman commands that interact with resources. It allows the operator to restrict the command to a subset of resources. For example, to get the status of all dev resources:

bossman status dev*

It can be provided multiple times, which will restrict operation to the subset of resources whose paths match any of the patterns.

Path matching details

It performs partial matching on resource paths using Unix filename pattern matching.

Pattern modifiers




Matches everything (including /)


Matches any single character (including /)


Matches any character in _seq_


Matches any character _not_ in _seq_

Assuming you have the following resources in your repository:

  • akamai, akam or akamai/*: will select all the resources

  • property or akamai/property: will select all Akamai properties

  • dev[1-2] will select all Akamai resources (properties and requestcontrol) for dev1 and dev2

  • dev[!3] will select all Akamai resources (properties and requestcontrol) for dev1 and dev2

Combining with shell expansion

Some shells, such as bash and zsh also support expansion patterns that can complement bossman’s pattern matching for very convenient operation. For example, to select all non-production resources with the set of resources above:

bossman status property/{dev\*,integration}
# gets expanded to the following by the shell
# bossman status property/dev* property/integration

bossman version

This command outputs the version. It is the only command that can be run before bossman init.

bossman init

This command must be run before anything can be done by Bossman. It adjusts the .git/config file, adds a [bossman] section and extra refspecs to all remotess, to ensure that git notes are properly pushed and pulled along with commits.

bossman status [glob*]

Provides synthetic information about the state of resources managed by bossman.

bossman apply [--since=commit] [glob*]

Deploys all pending commits.

--since limits deployment to commits after the given commit ref.

This should be avoided in general, since the default behavior is what one wants. It can be useful in some cases to avoid extraneous deployments on e.g. long lived branches, which should never be rebased.

Note that --since will deploy all commits after the given commit, non-inclusive.

For example:

Deploy the latest commit on the current branch:

bossman apply --since HEAD^

Deploy all the commits after integration was merged to the current branch:

bossman apply --since integration

bossman validate [glob*]

Validates the correctness of resources in the working copy.

This is the only command that does not operate on a commit.

bossman (pre)prerelease [--rev HEAD] [glob*]

  • prerelease: makes a given revision available to an internal audience, typically for testing

  • release: makes a given revision available to the end users

--rev can be any valid git commit reference, e.g.

  • a commit hash (full or abbreviated)

  • a tag name

  • a branch name

  • HEAD

  • a relative ref

bossman log [glob*]

Outputs the revision history of the selected resources.

Usage from CI

It is possible to use bossman from automation, but the bossman (pre)release commands require confirmation before they do anything, and expect to be run attended in a terminal, by default.

In automation, you will want to bypass confirmation, which can be done like this:

bossman prerelease --yes
bossman release --yes