Migration Guide to idf-ci 1.x

This guide outlines the breaking changes introduced in idf-ci 1.0.

Configuration Structure Changes

The artifact configuration structure has been reorganized for better clarity and flexibility:

Before (0.x):

[gitlab.artifacts]
s3_file_mode = "zip"

[gitlab.artifacts.s3_zip.flash]
bucket = "idf-artifacts"
zip_basedir_pattern = "**/build*/"
zip_file_patterns = [
    "bootloader/*.bin",
    "*.bin",
]

After (1.x):

[gitlab.artifacts.s3]
enable = true

# by default zip_first is false, so the files will be uploaded individually
[gitlab.artifacts.s3.configs.flash]
bucket = "idf-artifacts"
build_dir_pattern = "**/build*/"
patterns = [
    "bootloader/*.bin",
    "*.bin",
]

[gitlab.artifacts.s3.configs.metrics]
bucket = "idf-artifacts"
zip_first = false
patterns = [
    "**/size*.json"
]

Key Changes:

  • s3 and s3_zip configurations merged into s3.configs

    • Moved gitlab.artifacts.s3.[key] to gitlab.artifacts.s3.configs.[key]

    • Moved gitlab.artifacts.s3_zip.[key] to gitlab.artifacts.s3.configs.[key]

  • Renamed gitlab.artifacts.build_job_filepatterns to gitlab.artifacts.native.build_job_filepatterns

  • Renamed gitlab.artifacts.test_job_filepatterns to gitlab.artifacts.native.test_job_filepatterns

  • New options: is_public, zip_first for conditional artifact types

  • Mixed artifact type upload/download is now supported

Legacy compatibility for native artifact keys:

  • gitlab.artifacts.build_job_filepatterns and gitlab.artifacts.test_job_filepatterns still work in 1.x for backward compatibility.

  • When these legacy keys are used, idf-ci emits deprecation warnings and maps them to gitlab.artifacts.native.* internally.

  • If both the legacy key and the new gitlab.artifacts.native.* key are set, the new key takes precedence and the legacy one is ignored.

Recommended migration:

[gitlab.artifacts.native]
build_job_filepatterns = [
    "**/build*/bootloader/*.bin",
    "**/build*/*.bin",
]
test_job_filepatterns = [
    "pytest-embedded/",
    "XUNIT_RESULT*.xml",
]

Environment Variables

Removed:

  • IDF_S3_BUCKET (bucket now specified per artifact type in config)