Usage
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
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:
resources:
- module: bossman.plugins.akamai.property
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.
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.
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 [-e|--exact-match] [glob*]
Provides synthetic information about the state of resources managed by bossman.
bossman apply [--force] [--dry-run] [--since=commit] [-e|--exact-match] [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
--dry-run
simply evaluates which revisions would be deployed, without performing any action.
--force
indicates that the plugin should apply a change even if it might be unsafe. The implementation
and interpretation of “unsafe” is dependent on the plugin itself.
bossman validate [-e|--exact-match] [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] [-e|--exact-match] [glob*]
prerelease
: makes a given revision available to an internal audience, typically for testingrelease
: 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 [-e|--exact-match] [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