foremast.cfg /


This configuration holds information necessary for running foremast such as auth tokens, URLs, whitelists etc

Example Configuration

; foremast.cfg
domain =
envs = dev,stage,prod
regions = us-east-1,us-west-2
ami_json_url =
git_url =
gate_api_url =
templates_path = ../../foremast-templates
default_securitygroup_rules = { "bastion" : [ { "start_port": "22", "end_port": "22", "protocol": "tcp" } ],
                                "serviceapp" : [ { "start_port": "8080", "end_port": "8080", "protocol": "tcp" } ] }

gitlab_token = 123token23423343
slack_token = 123slack3203120312

asg_whitelist = application1,application2

app = {project}{repo}
dns_elb = lb-{project}{repo}.{env}.{domain}
s3_bucket = secret-{env}-{project}

default = 120
envs = { "dev" : { "deleteScalingPolicy": 240} }

    'base': {
        'domain': '',
        'envs': 'dev,stage,prod',
        'regions': 'us-east-1,us-west-2',
        'ami_json_url': '',
        'git_url': '',
        'gate_api_url': '',
        'templates_path': '../../foremast-templates',
        'default_securitygroup_rules': {
            'bastion': [{'start_port': '22', 'end_port': '22', 'protocol': 'tcp'}],
            'serviceapp': [{'start_port': '8080', 'end_port': '8080', 'protocol': 'tcp' }],
    'credentials': {
        'gitlab_token': '123token23423343',
        'slack_token': '123slack3203120312',

    'whitelists': {
        'asg_whitelist': 'application1,application2',
    'formats': {
        'app': '{project}{repo}',
        'dns_elb': 'lb-{project}{repo}.{env}.{domain}',
        's3_bucket': 'secret-{env}-{project}',
    'timeouts': {
        'default': 120,
        'envs': { 'dev': { 'deleteScalingPolicy': 240 } },

Configuration Locations

Foremast will look in the following locations, in order, for the foremast.cfg or config file.

  1. ./.foremast/foremast.cfg
  2. ~/.foremast/.foremast.cfg
  3. /etc/foremast/foremast/cfg
  4. ./

Configuration Details


Sections for base information such as urls and general configurations


The base domain of your applications. Used for generating DNS

Required: Yes


Comma delimited list of environments/applications that will be managed with Foremast

Example: dev,stage,prod
Required: Yes


List of foremast managed Pipeline types to allow.

Type: str
Example: ec2,lambda,manual
Default: ec2,lambda
Required: No


Comma delimiated list of AWS regions managed by Foremast

Example: us-east-1,us-west-2
Required: Yes


FQDN of where to query for AMI ID look ups. See ami-lookup.json for more details

Required: No


FQDN of gitlab. Will be used for handling API calls to Gitlab

Required: No


FQDN Of your spinnaker Gate instance. This is where all API calls to Spinnaker will go

Required: Yes


Path to custom templates directory. If provided, Foremast will first look in this directory for any templates. This can be an absolute path, or a path relative to where you where you are running the Foremast commands. See Pipeline Flow and Examples for more details on custom templates.

Required: No


Comma separated list or json of EC2 security groups to include for all deployments. If a comma separated list is given, the groups are applied to all environments. If a json is provide, it assigns groups only to the specified environment.

Required: No
Example: office,test_sg,example
Example (json): {"dev": ["sg1", "sg2"], "stage": ["sg3"]}


Comma separated list or json of ELB security groups to include for all deployments. If a comma separated list is given, the groups are applied to all environments. If a json is provide, it assigns groups only to the specified environment.

Required: No
Example: test_sg,example_elb_sg
Example (json): {"dev": ["sg1", "sg2"], "stage": ["sg3"]}


Security group rules that should be included by default for the application specific group. If $self is used as the security group name, it will self-reference to its own application name.

Required: No
Example: { "bastion" : [ { "start_port": "22", "end_port": "22", "protocol": "tcp" } ] }


If accessing Gate via x509 certificate authentication, this value provides the local path to the certificate. Only PEM certs are supported at this time (containing both the key and certificate in the PEM).

Required: No
Example: /var/certs/gate-cert.pem


If accessing Gate via x509 leveraging a custom certificate authority (such as acting as your own CA), this value provides the local path to the CA bundle. It is recommended to use an existing CA Bundle and append your CA certificate to it (

Required: No
Example: /var/certs/CA.pem


Section for handling credential configurations such as tokens, usernames, and passwords


Gitlab token used for authentication in Foremast

Required: No


Slack token used for authentication when sending Slack messages from Foremast

Required: No


Sections for configuring whitelist info


Comma delimiated list of applications to whitelist from ASG rules

Required: No


Section handling the naming convention of applications, elb, iam, s3 buckets and other services.

The most common sections are shown. The complete list of sections and defaults are defined by the underlying library gogo-utils.

Any of the possible variables below can be used as the value.

  • domain organization domain
  • env dev, qa, production, etc
  • project lowercase git group/organization
  • repo lowercase git project/repository
  • raw_project git group/organization
  • raw_repo git project/repository


A string of your organization’s domain

Required: No


A string of the format of your application

Default: {repo}{project}
Required: No


An FQDN of your application’s Elastic Load Balancer (ELB)

Default: {repo}.{project}.{env}.{domain}
Required: No


An string of your base S3 bucket name

Default: archaius-{env}
Required: No


An string of the format of the application’s jenkins job name

Default: {project}_{repo}
Required: No


Section handling customization of task timeouts when communicating with Spinnaker. Timeouts can vary per environment and per task.


The default task timeout value

Default: 120
Required: No


A json object keyed by environment name. Each value should be a json object keyed by task name.

Default: 120
Required: No