> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Working with the Cognite Toolkit in a team

> Learn how to prevent configuration conflicts with the Cognite Toolkit using multiple config files, git diff module selection, and deployment protection.

Use this page when several people change the Cognite Toolkit configuration for one Cognite Data Fusion (CDF) project. You will build several config files in one command, deploy only the modules Git shows as changed, and stop two people from deploying the same module at the same time.

> [!WARNING]
>
> These steps use [alpha flags](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md). The flags are experimental and may change or be removed without notice. Enable them on a shared development project. For staging and production, deploy with your continuous integration and continuous delivery (CI/CD) pipeline.

Before you begin, ensure you have:

* Installed the Cognite Toolkit `0.9.9` or later for multiple config files, `0.9.21` or later for git diff selection, and `0.9.26` or later for deployment protection. Version details are on [Alpha flags](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md).
* Completed [Setting up the Cognite Toolkit locally](https://docs.cognite.com/cdf/deploy/cdf_toolkit/guides/setup.md).
* Initialized a project repository with a [`cdf.toml`](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/cdf_toml) file and environment configuration files.
* Confirmed access to a Git repository and a CI/CD pipeline.

## Understanding collaboration challenges

When you configure CDF projects across multiple sites, several team members often change configuration at the same time. Projects also span development, testing, staging, and production. Uncoordinated edits then overwrite each other's work during merges and deployments, and resource definitions drift when people skip configuration best practices.

This page shows how to prevent those conflicting changes. For inconsistent configurations, use the Cognite Toolkit [validation rules](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/cdf_toml.md#the-rules-section). To promote a configuration from development to production, follow [Setting up CI/CD for the Cognite Toolkit](https://docs.cognite.com/cdf/deploy/cdf_toolkit/guides/cicd.md).

## Setting up the team

To collaborate effectively when managing CDF configurations with the Cognite Toolkit, follow these recommended practices:

**Use version control**. Manage all configuration files in a version control system such as Git. This tracks configuration history and allows you to revert changes when needed.

**Use a monorepo**. Store all module and environment configurations in a single repository. A monorepo provides a single source of truth and simplifies dependency management between resources.

**Protect default branches**. Enable branch protection on default branches (such as `main`). Require team members to propose changes through pull requests to ensure code review and automated validation before merging.

**Automate with CI/CD**. Implement a CI/CD pipeline to validate and deploy configuration changes automatically. Run automated checks on every pull request, and use a deployment pipeline on the default branch to publish changes to the target CDF environment.

## Editing modules

Follow this workflow when modifying configuration modules:

**1. Create a feature branch**

Create a branch from the default branch (`main`). Use a descriptive branch name that follows your team's naming conventions.

**2. Edit the module**

Edit only the module files relevant to your change in your local branch.

**3. Create a pull request**

Open a pull request targeting the default branch. Include a clear description of the proposed configuration changes.

**4. Run automated checks**

Verify that all automated CI/CD checks pass, including `cdf build` validation.

**5. Request a review**

Request a review from your team or designated module owners.

**6. Apply requested changes**

If reviewers request changes, commit and push updates to your feature branch. The pull request updates automatically.

**7. Merge the pull request**

After receiving approvals and passing all checks, merge the pull request into the default branch.

**8. Deploy changes**

The CI/CD pipeline deploys the merged configuration to the target CDF environment.

Confirm that the pipeline run succeeds and that the resources in the target CDF project match the merged module files.

## Building multiple config files

Teams often maintain a single [`config.[env].yaml`](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/config_yaml) file per environment, such as `config.dev.yaml`. When multiple team members edit the `variables` section at the same time, merge conflicts can occur.

You can split that configuration into site-specific files, such as `config.site1-dev.yaml` and `config.site2-dev.yaml`. Building those files in separate commands can produce conflicting resource definitions. Build them in one `cdf build` command so the Cognite Toolkit checks that the resources agree.

**1. Enable multiple config files**

Set the `multi-configs` [alpha flag](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md) in `cdf.toml`:

```toml cdf.toml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
[alpha_flags]
multi-configs = true
```

**2. Build the config files together**

Pass each file to `cdf build`. Use the same `environment.project` and the same `environment.validation-type` in every file. `environment.selected` and `variables` stay independent, so each file can build the same modules with different variable values.

```shell theme={"languages":{"custom":["/_languages/kuiper.json"]}}
cdf build --config-yaml config.site1-dev.yaml --config-yaml config.site2-dev.yaml
```

**3. Confirm the build**

`cdf build` completes. The Cognite Toolkit validates the resources from every config file in that command. When `environment.project` or `environment.validation-type` differs between the files, align those fields and run the command again.

## Selecting changed modules with git diff

Git diff selection builds and deploys only modules whose YAML files changed relative to `deploy-branch`. Enable it with the `git-diff-select` [alpha flag](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md), then set `selection-type: git-diff`.

Use git diff selection on a shared development project. In staging and production, deploy every configured module through your CI/CD pipeline.

Selecting every module on each deploy can overwrite work that other people still have on feature branches. This `config.dev.yaml` does that:

```yaml config.dev.yaml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  selected:
    - modules/
```

With this configuration, every merge to the default branch builds and deploys all modules. Commenting modules out of `environment.selected` by hand is easy to get wrong:

```yaml config.dev.yaml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  selected:
    # - modules/another_module
    - modules/my_module
```

**1. Enable git diff selection**

Set the `git-diff-select` alpha flag in `cdf.toml`:

```toml cdf.toml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
[alpha_flags]
git-diff-select = true
```

**2. Point selection at the deploy branch**

In the environment configuration file, set `selection-type` to `git-diff`, set `validation-type` to `dev`, and set `deploy-branch` to the branch you deploy from. The Cognite Toolkit rejects `selection-type: git-diff` when `validation-type` is anything other than `dev`.

```yaml config.dev.yaml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  selection-type: git-diff
  deploy-branch: main
```

**3. Commit the module YAML**

Commit the changed `.yaml` and `.yml` files under `modules/` before you build. Git diff selection reads committed files. When those files are still uncommitted, `cdf build` stops and lists them.

**4. Build and deploy the changed modules**

Run `cdf build`, then `cdf deploy`.

On a feature branch, the Cognite Toolkit runs `git diff` against `deploy-branch` and builds only the modules that differ.

On `deploy-branch`, the Cognite Toolkit runs `git diff` against the previous commit. Merge pull requests into that branch with **Squash and merge**. Otherwise, that diff cannot detect the full set of changed modules.

**5. Confirm the selection**

Run `cdf build --verbose`. The Selection section lists only the module paths that differ from `deploy-branch`.

When no module YAML differs from `deploy-branch`, the command stops with `No modules were found to build based on the git diff selection`.

## Protecting deployments from concurrent overwrites

Deployment protection stops two people from deploying the same module to a shared development project at the same time. Enable it with the `deploy-protection` [alpha flag](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md), then set `deploy-protection: protected`. You can use it with or without git diff selection.

In staging and production, run deployments through your CI/CD pipeline. Deployment protection is for shared development projects. It leaves access control unchanged, and a person who already holds the lock can deploy again from that same branch.

**1. Enable deployment protection**

Set the `deploy-protection` alpha flag in `cdf.toml`:

```toml cdf.toml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
[alpha_flags]
deploy-protection = true
```

**2. Protect the development environment**

In the environment configuration file, set `deploy-protection` to `protected` and set `deploy-branch`.

```yaml config.dev.yaml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  deploy-branch: main
  deploy-protection: protected
```

To combine deployment protection with git diff selection, add `selection-type` to that same `environment` block:

```yaml config.dev.yaml theme={"languages":{"custom":["/_languages/kuiper.json"]}}
environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  selection-type: git-diff
  deploy-branch: main
  deploy-protection: protected
```

**3. Deploy from your branch**

Run `cdf deploy` from a Git repository.

On a feature branch, the Cognite Toolkit requests a lock for each module in the deployment. It grants the lock when the module is unlocked, the lock is already on your current branch, or the lock is more than 24 hours old. When another branch holds a current lock, `cdf deploy` stops and deploys nothing.

On `deploy-branch`, `cdf deploy` takes the locks for the modules in the deployment and releases them when the deployment finishes.

**4. Confirm the locks**

A successful deploy prints a panel titled `Successfully acquired locks.` followed by the module identifiers.

When another branch holds a lock, the command stops with `Failed to acquire locks for modules:` and names the module, the Git user who holds the lock, and that user's branch.

After a successful deploy on `deploy-branch`, the Cognite Toolkit prints a panel titled `Successfully released locks.`

## Further reading

* [Alpha flags](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/alpha_flags.md)
* [config.\[env\].yaml](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/config_yaml)
* [cdf.toml](https://docs.cognite.com/cdf/deploy/cdf_toolkit/api/cdf_toml.md)
* [Setting up CI/CD for the Cognite Toolkit](https://docs.cognite.com/cdf/deploy/cdf_toolkit/guides/cicd.md)
* [Setting up the Cognite Toolkit locally](https://docs.cognite.com/cdf/deploy/cdf_toolkit/guides/setup.md)