Configuration Reference

diid-push uses a YAML configuration file (by default diid.yaml) to declare integrations, schedules, and API specification sources.

An annotated reference template can be found in examples/diid.example.yaml.

Schema Overview

Key	Required	Description
apiVersion	Yes	Must be set to diid.dev/v1beta1
kind	No	SyncConfig
integrations	No	Array of external integration authentication configs
schedules	No	Array of named cron schedule expressions
specs	Yes	Array of specification sources to synchronize

---

Environment Variable Expansion

All string fields support ${VAR_NAME} syntax for expanding process environment variables at runtime. Undefined variables expand to empty strings.

Example:

specs:
  - name: payments-api
    type: file
    pushToken: ${DIID_PAYMENTS_TOKEN}
    file:
      path: ./openapi.yaml

---

Integrations

Integrations provide shared authentication parameters referenced by source specifications.

Backstage Integration (type: backstage)

integrations:
  - name: backstage-internal
    type: backstage
    baseUrl: https://backstage.internal.example.com
    auth:
      type: static-token
      token: ${BACKSTAGE_TOKEN}

Field	Required	Description
name	Yes	Unique identifier referenced by specs[].backstage.integrationRef
type	Yes	Must be backstage
baseUrl	Yes	Base URL of the Backstage API endpoint
auth.type	No	Authentication type (static-token)
auth.token	No	Bearer token value

GitHub Integration (type: github)

integrations:
  - name: github-org
    type: github
    auth:
      type: token
      token: ${GITHUB_TOKEN}

Field	Required	Description
name	Yes	Unique identifier referenced by specs[].github.integrationRef
type	Yes	Must be github
auth.type	No	Authentication type (token)
auth.token	No	GitHub personal access token or fine-grained repository token

---

Schedules

Schedules define named cron expressions used by specs.

schedules:
  - name: hourly
    cron: "0 0 * * * *"
  - name: every-15min
    cron: "0 */15 * * * *"

Field	Required	Description
name	Yes	Unique identifier referenced by specs[].scheduleRef
cron	Yes	Standard 5-field cron expression

Specs without a scheduleRef execute once during daemon initialization, or immediately when using --once.

---

Specs

Each item in specs defines an API specification source and target push credentials.

Common Spec Fields

Field	Required	Description
name	Yes	Unique human-readable spec identifier
type	Yes	Source driver (http, file, backstage, github)
pushToken	Yes	diid project push token
scheduleRef	No	Reference to a schedule defined in schedules

Source Drivers

HTTP Driver (type: http)

Retrieves spec content via HTTP or HTTPS.

specs:
  - name: payments-api
    type: http
    pushToken: ${DIID_PAYMENTS_TOKEN}
    scheduleRef: hourly
    http:
      url: http://payments.svc.cluster.local/openapi.json
      headers:
        Authorization: "Bearer ${PAYMENTS_TOKEN}"
      timeout: 30s
      skipTlsVerify: false

Field	Required	Description
url	Yes	Target HTTP/HTTPS endpoint
headers	No	Key-value map of HTTP request headers
timeout	No	Timeout duration string (default 30s)
skipTlsVerify	No	Disable TLS certificate verification (default false)

Note: HTTP redirects are intentionally disabled.

File Driver (type: file)

Reads spec content from a local disk file.

specs:
  - name: orders-api
    type: file
    pushToken: ${DIID_ORDERS_TOKEN}
    file:
      path: ./specs/orders-openapi.yaml

Field	Required	Description
path	Yes	Absolute or relative file path

Backstage Driver (type: backstage)

Fetches spec content from a Backstage entity catalog definition (spec.definition).

specs:
  - name: inventory-api
    type: backstage
    pushToken: ${DIID_INVENTORY_TOKEN}
    scheduleRef: hourly
    backstage:
      integrationRef: backstage-internal
      entityRef: "api:default/inventory-service"

Field	Required	Description
integrationRef	Yes	Reference to an integration named under integrations
entityRef	Yes	Backstage entity reference (kind:namespace/name)

Entity reference parsing defaults:

• Default namespace: default
• Default kind: component

GitHub Driver (type: github)

Downloads raw spec files from GitHub using the Repository Contents API.

specs:
  - name: notifications-api
    type: github
    pushToken: ${DIID_NOTIFICATIONS_TOKEN}
    scheduleRef: every-15min
    github:
      integrationRef: github-org
      owner: my-org
      repo: notifications-service
      path: docs/openapi.yaml
      ref: main

Field	Required	Description
integrationRef	Yes	Reference to an integration named under integrations
owner	Yes	GitHub user or organization name
repo	Yes	Repository name
path	Yes	Repository file path
ref	No	Git ref (branch, tag, or commit SHA; defaults to default branch)