Gimbal aims to make auditing an application as simple and as configuration free as possible but no two applications are exactly the same. Gimbal provides the mechanism to easily configure it using a configuration file.

To use a configuration file, where gimbal is being executed at should contain a .gimbalrc.yml, .gimbalrc.yaml, .gimbalrc.json, or .gimbalrc.js file. Here are some examples:

configs:
  puppeteer:
    headless: false

outputs:
  json: ./artifact/gimbal.json

{
  "configs": {
    "puppeteer": {
      "headless": false
    }
  },
  "outputs": {
    "json": "./artifact/gimbal.json"
  }
}

module.exports = {
  configs: {
    puppeteer: {
      headless: false,
    },
  },
  outputs: {
    json: './artifact/gimbal.json',
  },
};

module.exports = async () => {
  const configs = await getGimbalConfigs();
  const outputs = await getGimbalOutputs();

  return {
    configs,
    outputs,
  };
};

You can pass Lighthouse configuration straight to the lighthouse object:

configs:
  lighthouse:
    maxWaitForFcp: 120000;
    outputHtml: artifacts/lighthouse.html

A configuration file can specify what specific audits to run. With this, you can just run gimbal in the directory where the configuration file is in and it will only run those audits. For example, if you wanted to run the lighthouse and size audits, you would specify the audits array:

audits:
  - lighthouse
  - size

A configuration file can also specify what commands to run. This means, if you have a configuration file that specifies what jobs, then all you need to do is execute gimbal in that directory and Gimbal will run those commands for you. Example:

jobs:
  - audit
  - size --cwd ./foo/bar