From 9ce3da4d59cb61e24c126a0e466036011f9826d4 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 11 Mar 2026 07:56:15 +0000 Subject: [PATCH 1/2] docs: add field-level ignore syntax to .kbcignore documentation Co-Authored-By: Martin Vasko --- cli/structure/index.md | 54 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/cli/structure/index.md b/cli/structure/index.md index 1ad98870..317af371 100644 --- a/cli/structure/index.md +++ b/cli/structure/index.md @@ -452,8 +452,14 @@ Example: You can exclude specific configurations from the sync process by creating a `.kbcignore` file in the `.keboola` directory. -It is a plain text file where each line specifies a path to a configuration or configuration row in the format -`{component_id}/{configuration_id}/{row_id}`. The `row_id` is optional for [row-based configurations](https://help.keboola.com/components/#configuration-rows). +It is a plain text file where each line specifies either: + +- A path to a **configuration or configuration row** to exclude entirely, in the format `{component_id}/{configuration_id}/{row_id}` (the `row_id` is optional for [row-based configurations](https://help.keboola.com/components/#configuration-rows)). +- A **field-level ignore** rule in the format `{component_id}/{configuration_id}:{field_name}`, which excludes a single field from synchronization while keeping the rest of the configuration managed by the CLI. + +Comments (lines starting with `#`) and empty lines are ignored. + +### Configuration and Row Ignore Example `.kbcignore` file: @@ -469,6 +475,50 @@ This excludes: As a result, the `kbc sync pull` and `kbc sync push` commands will not synchronize these configurations. +### Field-Level Ignore + +In addition to ignoring entire configurations or rows, you can ignore **individual fields** within a configuration. +This is useful when you want to manage most of a configuration via the CLI but let a specific field be controlled +exclusively in the Keboola UI (or vice versa). + +The syntax is: + +``` +{component_id}/{configuration_id}:{field_name} +``` + +Where `field_name` is either: + +- A **struct-level field** of the configuration — currently `isDisabled` is supported. +- A **dot-notation content key** referring to a path inside the configuration's `config.json` content, e.g., `schedule.cronTab`. + +Example `.kbcignore` with field-level rules: + +``` +# Ignore the isDisabled flag — let the UI control whether this config is enabled +ex-generic-v2/798412456:isDisabled + +# Ignore the cron schedule — let the UI control the schedule timing +keboola.scheduler/801234567:schedule.cronTab +``` + +Field-level ignore is **bidirectional**: + +- **`kbc push`**: The remote value of the ignored field is kept. Any local change to that field is discarded before + the diff is computed, so the field is never pushed. +- **`kbc pull`**: The local value of the ignored field is kept. Any remote change to that field is discarded before + the diff is computed, so the field is never pulled. + +In both cases the rest of the configuration is synchronized normally. + +
+

Note:
+ The field-level ignore format requires exactly two path segments before the colon + (componentID/configID). The field name must not be empty or start/end with a dot.

+
+ +### Configuration-Level Ignore + **`kbc push` operation** The `kbc push` command will skip the excluded configurations and will not push them back to the project, even if they exist or have been modified in the local folder structure. From ad73021e6b4aad721cfd6ef78f06c6a538911124 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 11 Mar 2026 08:21:57 +0000 Subject: [PATCH 2/2] docs: address Copilot review comments on .kbcignore docs Co-Authored-By: Martin Vasko --- cli/structure/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cli/structure/index.md b/cli/structure/index.md index 317af371..5ca86233 100644 --- a/cli/structure/index.md +++ b/cli/structure/index.md @@ -450,7 +450,7 @@ Example: ``` ## .kbcignore -You can exclude specific configurations from the sync process by creating a `.kbcignore` file in the `.keboola` directory. +You can exclude specific configurations, configuration rows, or individual fields from the sync process by creating a `.kbcignore` file in the `.keboola` directory. It is a plain text file where each line specifies either: @@ -504,17 +504,17 @@ keboola.scheduler/801234567:schedule.cronTab Field-level ignore is **bidirectional**: -- **`kbc push`**: The remote value of the ignored field is kept. Any local change to that field is discarded before +- **`kbc sync push`**: The remote value of the ignored field is kept. Any local change to that field is discarded before the diff is computed, so the field is never pushed. -- **`kbc pull`**: The local value of the ignored field is kept. Any remote change to that field is discarded before +- **`kbc sync pull`**: The local value of the ignored field is kept. Any remote change to that field is discarded before the diff is computed, so the field is never pulled. In both cases the rest of the configuration is synchronized normally. -
+
### Configuration-Level Ignore