Write Static Config App

How To Write A Static Config App (JavaScript)

When writing a static config file using the CircleCI Config SDK, it is possible to write your config app and compile the config file locally with the help of git pre-hooks. No YAML is required.

Familiarize yourself with the process of generating a dynamic config, as much of the process is the same.

How to write a dynamic config app

When writing a static config app, no original config.yml is needed, as it will be generated at the time the commit message is created.

Begin with a similar structure shown in the dynamic config example, without the config.yml. In this example, the source directory has also been named static/

└── .circleci/
    └── static/
        ├── executors/
        │   └── docker-node.js
        ├── jobs/
        │   ├── jobA.js
        │   └── jobB.js
        ├── app.js
        └── package.json

The main difference between this application and the dynamic application is where and when the config is generated. In a "dynamic" config app, the config is generated "just-in-time" in the CircleCI platform. Using this static method, the config will be generated locally on our machine with the help of a tool called husky.

Setup Source

You can use the same sample code as the dynamic sample project

1. cd into the source directory cd .circleci/static/ to modify our static config app.
2. Run npm init or yarn init to initiate the app and create a package.json file. a. Once entered, a prompt will appear asking a series of questions. Enter any values you prefer or leave the defaults except for main, ensure this property has the value app.js
3. Create an npm script to generate the config file.

We can generate the config file ourselves by executing the app.js file with node, but to make the git-hook easier, we will also add an npm script to the package.json file like so:

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node index.js"
  },

Setup Husky

Because our config file in this example is "static", we need to generate it before our changes are committed. This way, if we update our Javascript config app, we ensure those changes are reflected in the YAML config file stored in the repo. This can be done automatically with git hooks, made even easier for node projects with a utility called husky. We will use husky to automatically regenerate our config file on every commit.

Note: commit hooks run locally, this will not work if you edit files on GitHub.com directly.

1. cd into your config project directory, at the same level as the package.json file
2. Follow the husky usage documentation to install and configure husky

npx husky-init && npm install     # npm
npx husky-init && yarn            # Yarn 1

This will install husky and add a pre-commit hook, which by default will run npm test on every commit. We will edit this to instead, generate our config.

3. edit .husky/pre-commit

Edit the contents of .husky/pre-commit, to run the npm run start command we configured to generate the config.yml file

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run start

Your Javascript app will either need to create the file as config.yml and write it to .circleci/config.yml relative to the repo, or you can move the file as part of the hook.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run start && mv dynamicConfig.yml ../config.yml