idf-ci

A tool designed to streamline CI/CD for ESP-IDF projects, with support for both GitLab CI/CD and GitHub Actions.

Installation

pip install -U idf-ci

Key Features

• Sensible Defaults

  Easy setup with default settings for idf-build-apps and pytest-embedded.

• Build Management

  Build ESP-IDF apps for multiple targets (ESP32, ESP32-S2, ESP32-C3, etc.) with parallel builds and smart filtering based on changed files or test needs.

• Test Management

  Run pytest with ESP-IDF configs, including target-specific test discovery and marker filtering.

• GitLab CI/CD Integration

  Full pipeline support with artifacts, S3 uploads, and auto-generated jobs for builds and tests.

• GitHub Actions Integration

  Generate test matrix from project settings.

Basic Usage

Initialize Configuration Files

# Create .idf_ci.toml with default idf-ci settings
idf-ci init

# Create .idf_build_apps.toml with default build settings
idf-ci build init

# Create pytest.ini with default test settings
idf-ci test init

Build Apps

# Build all apps
idf-ci build run

# Build apps for a specific target
idf-ci build run -t esp32

# Build only test-related apps
idf-ci build run --only-test-related

# Preview what would be built (dry run)
idf-ci build run --dry-run

Run Tests

We provide a pytest plugin that works with pytest-embedded to run tests with sensible defaults.

# Only collect tests that would run
pytest --collect-only

# Run tests for the esp32 target
pytest --target esp32

Agent skill

For an AI agent using idf-ci in another ESP-IDF project, install the idf-ci skill. It includes a command map, runnable examples, environment-variable formats, and safety checks for CI and artifacts. The agent should still check the installed CLI's --help before running a command.

• Hermes Agent: hermes skills install espressif/idf-ci/skills/idf-ci
• Agents supported by the skills CLI: npx skills add espressif/idf-ci --skill idf-ci

The skill is self-contained in skills/idf-ci/; it is not automatically loaded by installing the Python package.

Documentation

For detailed usage and configuration options, please refer to the documentation.