# Version Dependencies

`version.dependencies` is the base catalog of software versions Atmos tracks. Despite the field name, entries do not have to be locally installed dependencies. They can be any software version Atmos should resolve, lock, and optionally render into project files.

Use this catalog for local tool versions, GitHub Actions refs, container images, Helm chart versions, release tags, and other software versions that need deterministic policy.

## Configuration

**File:** `atmos.yaml`

```yaml
version:
  dependencies:
    opentofu:
      ecosystem: toolchain
      datasource: toolchain
      package: opentofu
      desired: "~1.10"
      group: infrastructure

    checkout:
      ecosystem: github/actions
      datasource: github-tags
      provider: github
      package: actions/checkout
      desired: v6
      update:
        pin: sha
      exclude:
        - v6.0.0
      prerelease: false

    nginx:
      ecosystem: oci
      datasource: oci-tags
      provider: dockerhub
      package: library/nginx
      desired: "1.29.0"
```

## Fields

- **`ecosystem`**
  Software domain, such as 
  `toolchain`
  , 
  `github/actions`
  , 
  `github`
  , 
  `oci`
  , 
  `docker`
  , 
  `helm`
  , 
  `terraform`
  , or 
  `opentofu`
  .
- **`datasource`**
  Version lookup strategy, such as 
  `toolchain`
  , 
  `github-tags`
  , 
  `github-releases`
  , 
  `oci-tags`
  , 
  `docker-tags`
  , or 
  `helm`
  .
- **`provider`**
  Provider name from 
  `version.providers`
  .
- **`package`**
  Package coordinate understood by the datasource.
- **`desired`**
  Desired version expression: concrete version, SemVer constraint, or 
  `latest`
  .
- **`group`**
  Group name used for shared policy and filtered operations.
- **`update`, `include`, `exclude`, `prerelease`, `labels`**
  Entry-level policy. Candidate filters on an entry are the most specific policy scope.

## Example

```shell
atmos version track add checkout --package=actions/checkout --desired=v6 --pin=sha
atmos version track add opentofu --desired="~1.10"
atmos version track set checkout --exclude=v6.0.0 --prerelease=false
```