idf-ci Configuration

This guide explains how to inspect and override idf-ci settings. For command syntax and options, see CLI Commands.

Check the current configuration

Use the config command group to inspect the effective configuration after all overrides are applied.

Show a resolved value and its source (default, config file, or CLI override):

idf-ci config show gitlab.project

Understand a config key

Use explain to see a key’s type, default, and available subkeys:

idf-ci config explain gitlab

Use dot-separated paths for nested keys:

idf-ci config explain gitlab.build_pipeline.runs_per_job

Put overrides in a TOML file

Create or edit .idf_ci.toml at your repository root:

[gitlab.build_pipeline]
runs_per_job = 10
workflow_name = "A workflow name"

You can also generate a starter file with:

idf-ci init

If the file lives elsewhere, point to it with --config-file.

Component Mapping and Modified Files

idf-ci determines which ESP-IDF components are affected by modified files so CI pipelines only build what changed.

Configure component extraction rules and ignored extensions in .idf_ci.toml:

component_mapping_regexes = [
    "/components/(.+)/",
    "/common_components/(.+)/",
]

component_ignored_file_extensions = [
    ".md",
    ".rst",
    ".yaml",
    ".yml",
    ".py",
]

Test how your rules map changed files to components with get-modified-components:

idf-ci config get-modified-components \
  --modified-files "components/esp_wifi/src/wifi.c;docs/index.rst"

Override values from the CLI

Use dot-path assignments with --config. If there are spaces around =, quote the whole assignment. Values use Python literal syntax (10, True, "str", {...}, [...]).

# with spaces (quote it)
idf-ci --config 'gitlab.build_pipeline.runs_per_job = 10' ...

# without spaces
idf-ci --config 'gitlab.build_pipeline.workflow_name="A workflow name"' ...

# multiple overrides
idf-ci \
  --config 'gitlab.build_pipeline.runs_per_job=10' \
  --config 'gitlab.build_pipeline.workflow_name="A workflow name"' \
  ...

Understand how config is resolved

Configuration resolution (highest to lowest priority):

• CLI overrides (--config)

• Config file (.idf_ci.toml or --config-file)

• Defaults

Config file discovery searches upward from the current working directory for .idf_ci.toml. Use --config-file to bypass discovery and point to an explicit file.

Where to find default values

See the reference: CI Config File (all fields and defaults). You can expand “Show JSON schema” to see the full structure.