Specifications¶

Overview¶

Makim uses a YAML-based configuration file (.makim.yaml) to define tasks, dependencies, and execution environments. This document provides a detailed specification of all components available in a Makim configuration file.

1. File Structure¶

A .makim.yaml file consists of the following top-level sections:

groups
scheduler
hosts
vars
env
env-files

Each section is explained below in detail.

2. Groups¶

Description¶

Defines collections of related tasks. Each group contains tasks and environment variables specific to that group.

Structure¶

groups:
  <group_name>:
    env:
      <key>: <value>
    tasks:
      <task_name>: <task_definition>

Example¶

groups:
  build:
    env:
      BUILD_DIR: dist
    tasks:
      clean:
        help: Clean build artifacts
        run: rm -rf ${{ env.BUILD_DIR }}
      compile:
        help: Compile the project
        run: echo "Compiling..."

3. Tasks¶

Description¶

Tasks define executable commands with optional arguments, dependencies, and hooks.

Structure¶

tasks:
  <task_name>:
    help: <description>
    args: <arguments>
    env: <environment_variables>
    hooks: <pre-run/post-run/failure_hooks>
    matrix: <parameter_combinations>
    log: <file_logging_configuration>
    if: <validation_conditionals>
    options: <additional_options>
    run: <command>

Example¶

tasks:
  test:
    help: Run tests
    args:
      verbose:
        type: bool
        action: store_true
    run: pytest --verbose=${{ args.verbose }}

4. Arguments¶

Description¶

Defines arguments that tasks can accept with types, defaults,help descriptions and validation options.

Structure¶

args:
  <arg_name>:
    type: <type>
    default: <default_value>
    interactive: <true/false>
    help: <description>
    validations:
      <validation-type>: <validation_value>

You can provide validation-type options similar to JSON schema validation options

Example¶

args:
  env:
    type: string
    default: "dev"
    help: Environment setting
  username:
    type: string
    help: Username for system access
    validations:
      min-length: 3
      max-length: 32

5. Hooks¶

Description¶

Hooks define tasks that run before (pre-run) or after (post-run) a task executes or after (failure) a task execution fails. They can also include an if condition to control when the hook should be triggered.

Structure¶

hooks:
  pre-run:
    - task: <task_name>
      if: <condition>
  post-run:
    - task: <task_name>
      if: <condition>
  failure:
    - task: <task_name>
      if: <condition>

Example¶

tasks:
  build:
    hooks:
      pre-run:
        - task: clean
          if: ${{ vars.REBUILD == "true" }}
      post-run:
        - task: notify
      failure:
        - task: failure-notify
    run: echo "Building project..."

6. Environment Variables¶

Description¶

Defines global, group, or task-specific environment variables.

Structure¶

env:
  <key>: <value>

Example¶

env:
  API_KEY: abc
  RETRY_COUNT: "3"

Note:¶

⚠️ The value of an environment variable should always be a string. If you need to pass an integer, wrap it in quotes ("") to avoid type issues.

7. Matrix Configuration¶

Description¶

Defines multiple combinations of parameters for running a task.

Structure¶

matrix:
  <param_name>:
    - <value1>
    - <value2>

Example¶

matrix:
  python_version:
    - 3.8
    - 3.9
    - 3.10
  os:
    - ubuntu
    - macos

8. Scheduler¶

Description¶

Defines scheduled tasks using cron syntax, allowing periodic execution of tasks.

Structure¶

scheduler:
  <schedule_name>:
    task: <task_name>
    schedule: <cron_expression>

Example¶

scheduler:
  daily-clean:
    task: build.clean
    schedule: "0 0 * * *"

Understanding Cron Syntax¶

A cron expression consists of five fields, each representing a time unit:

Field	Value Range	Example	Meaning
Minute	`0-59`	`30`	Runs at 30th minute
Hour	`0-23`	`2`	Runs at 2 AM
Day of Month	`1-31`	`15`	Runs on the 15th day of the month
Month	`1-12`	`6`	Runs in June
Day of Week	`0-6` (Sunday = 0)	`1`	Runs on Monday

Common Cron Examples¶

0 0 * * * → Runs daily at midnight
30 14 * * 5 → Runs every Friday at 2:30 PM

For a detailed guide on cron syntax, visit:

📌 Cron Syntax Guide

9. Remote Hosts¶

Description¶

Defines SSH configurations for executing tasks on remote servers. Additionally, tasks can specify a remote entry to execute commands on a defined host.

Structure¶

hosts:
  <host_name>:
    username: <user>
    host: <hostname>
    port: <port>
    password: <password>

Using Remote Execution Inside a Task

tasks:
  <task_name>:
    remote: <host_name>
    run: <command>

Example¶

1. Define Remote Host¶

hosts:
  production:
    username: user
    host: example.com
    port: 22

2. Execute Task on Remote Server¶

tasks:
  deploy:
    remote: production
    run: echo "Deploying application..."

Explanation:

The hosts section defines the production remote server.
The deploy task specifies remote: production, ensuring it runs on example.com via SSH.

10. File Logging¶

Description¶

Defines the configuration for tasks to write their output to a file with optional custom formatting and control over which output types are logged.

Structure¶

log:
  path: <log_file_path>
  level: <output_type>
  format: <log_format_string>

Example¶

tasks:
  build:
    help: Build the application
    log:
      path: ./logs/build.txt
      level: both
      format: "%(asctime)s - %(levelname)s - %(message)s"
    run: |
      echo "Building..."

Supported Format Placeholders¶

%(asctime)s — Timestamp of the log entry.
%(task)s — Name of the task being executed.
%(file)s — File name where the task is defined.
%(levelname)s — Output type label (OUT or ERR).
%(message)s — Actual log output.

11. Retry Mechanism¶

Description¶

Defines how many times a task should be retried upon failure and the delay between each attempt.

Structure¶

retry:
  count: <number_of_attempts>
  delay: <seconds_between_attempts>

Example¶

tasks:
  post-data:
    help: Make an API call to post data
    retry:
      count: 3
      delay: 10
    run: |
      curl --fail -X POST https://example.com/api/data

12. Ignore Error Option¶

Description¶

The ignore-errors option allows a task to continue executing subsequent tasks even if it fails. When ignore-errors: true is set under options, the failure of that task does not interrupt the execution flow.

Structure¶

options:
  ignore-errors: <true/false>

The default value for ignore-errors is set to false

Example¶

groups:
  deploy:
    tasks:
      clear-cache:
        help: Attempt to clear CDN cache (optional)
        options:
          ignore-errors: true
        run: |
          echo "Clearing CDN cache..."
          # Simulate possible failure
          assert 1 == 2

      deploy-app:
        help: Deploy the application
        run: echo "Deploying application to production..."

      main-deploy:
        help: Deployment pipeline
        hooks:
          pre-run:
            - task: deploy.clear-cache
            - task: deploy.deploy-app
        run: echo "Deployment complete."

13. Variables¶

Description¶

Defines reusable variables that can be referenced throughout the configuration.

Supported Scopes:¶

Global – Available everywhere.
Group – Available within a specific group.
Task – Available only within a task.

Structure¶

vars:
  <var_name>: <value>

Example¶

vars:
  PROJECT_NAME: MyApp
  TIMEOUT: 30

This can be used in tasks as:

tasks:
  deploy:
    run: echo "Deploying ${{ vars.PROJECT_NAME }} with timeout ${{ vars.TIMEOUT }}s"

14. Environment Variables¶

Description¶

Loads environment variables from external .env files. This is useful for managing secrets and configurations separately. You can specify a single file or multiple files.

Supported Scopes:¶

Global – Available everywhere.
Group – Available within a specific group.
Task – Available only within a task.

Structure¶

Single file:

env-files: <path_to_env_file>

Multiple files:

env-files:
  - <path_to_env_file_1>
  - <path_to_env_file_2>

When multiple files are specified, they are loaded in order. Variables from later files override those from earlier files.

Example¶

Single file:

env-files: .env

Multiple files:

env-files:
  - .env.defaults
  - .env.local

This will load environment variables from both files. Variables in .env.local will override those with the same name in .env.defaults.