devgrid.yml

The devgrid.yml file in your repository root tells the DevGrid CLI how to sync your project with the DevGrid platform. Commands like lint, dry_run, and sync read this file.

Run devgrid-cli init to scaffold a starter file, or create one manually using the reference below.

Example

# devgrid.yml
project:
  appId: my-app-short-id          # optional — string or integer
  components:
    - name: my-cool-api
      shortId: api-001            # required — string or integer
      api: swagger.yml            # optional — path to OpenAPI/Swagger spec
      manifest: package.json      # optional — path to package manifest
      attributes:
        custom_id: xyz456
        team: platform
      dependencies:               # shorthand — type is component-has-dependency
        - to: some-component-id
          attributes:
            note: primary database
        - to: another-component-id
      relationships:              # advanced — explicit relationship types
        - type: component-has-dependency
          to: legacy-service-id
          attributes:
            env: prod

    - name: my-cool-db
      shortId: db-001

configuration:
  dryRunOutput: file              # file (default) or stdout

Top-level structure

Field	Required	Description
`project`	Yes	Application and component definitions
`configuration`	No	CLI behavior settings

Unknown top-level keys are rejected by devgrid lint.

`project`

Field	Type	Required	Description
`appId`	string or integer	No	Application short ID on DevGrid. When omitted, component updates still work, but application-level relationships are skipped
`components`	array	Yes	List of components to sync

`project.components[]`

Each component describes a service, library, datastore, or other entity in your system.

Field	Type	Required	Description
`name`	string	Yes	Display name
`shortId`	string or integer	Yes	Unique short identifier used to match remote state
`attributes`	object	No	Free-form key-value metadata synced to DevGrid
`api`	string	No	Path to an API definition file (e.g. `swagger.yml`)
`manifest`	string	No	Path to a manifest file (e.g. `package.json`, `pom.xml`)
`dependencies`	array	No	Shorthand dependency list (see below)
`relationships`	array	No	Explicit relationships with custom types (see below)

Flexible short IDs: appId, shortId, and relationship/dependency to values accept either strings ("my-app") or integers (10005).

`dependencies` (shorthand)

Each item requires to (target component short ID). The CLI automatically creates a component-has-dependency relationship.

Field	Type	Required	Description
`to`	string or integer	Yes	Target component `shortId`
`attributes`	object	No	Metadata on the relationship

`relationships` (advanced)

Use when you need a relationship type other than the dependency shorthand.

Field	Type	Required	Description
`type`	string	Yes	Relationship type (e.g. `component-has-dependency`)
`to`	string or integer	Yes	Target component `shortId`
`attributes`	object	No	Metadata on the relationship

If the target component does not exist on DevGrid, the sync planner adds a WARN_MISSING_TARGET action instead of failing immediately.

`configuration`

CLI settings that do not affect DevGrid platform state.

Field	Type	Required	Default	Description
`dryRunOutput`	string	No	`file`	Where `dry_run` writes its plan: `file` or `stdout`

When dryRunOutput is file (default), the plan is written to devgrid_dry_run_plan.json in the current directory.

Optional appId workflow

You can manage components and component-to-component relationships without an application context:

project:
  components:
    - name: standalone-service
      shortId: svc-001
      dependencies:
        - to: other-svc

Application-level relationships (application_has_component) are skipped when appId is omitted.

Not supported

The following patterns appear in older documentation or examples but are not valid in current CLI versions:

Pattern	Why it fails
`technologies:` on a component	Not in the schema — `devgrid lint` will reject it
`{{ .ENV_VAR }}` template syntax in attributes	No template processing; values are stored literally
Extra fields such as `type:` on components	Schema uses `additionalProperties: false` — unknown keys fail lint

Attribute values must be static YAML. Set dynamic values through your CI environment before generating the file, or use plain string values.

Validate your file

devgrid-cli lint

This validates devgrid.yml against the JSON schema used by the CLI. Fix any reported errors before running sync.

Example

Top-level structure

project

project.components[]

dependencies (shorthand)

relationships (advanced)

configuration