Manifests

An Agoraform manifest is a versioned YAML document containing declarative provider configuration and desired resources.

apiVersion: agoraform.io/v1alpha1
providers:
  matomo:
    publish: true
    environment: live
resources:
  - address: matomo.goal.trial_started
    attributes:
      name: Trial Started
      matchAttribute: event_action
      pattern: trialStarted

Top-level fields

Field	Required	Description
apiVersion	yes	Must be agoraform.io/v1alpha1.
providers	no	Non-secret provider-specific desired state.
resources	no	Desired managed resources. Omitted or empty is valid.

Provider credentials, tokens, passwords, and other secrets must never be put in the manifest. They belong in runtime configuration such as environment variables or .agoraform.env.

Provider configuration is intentionally separate from credentials. Matomo publication settings belong in Git; MATOMO_TOKEN_AUTH does not. Google Ads has no non-secret YAML fields in v0.3.0; an empty providers.googleads: {} block is accepted and still validates environment credentials. Putting OAuth secrets or the developer token in the manifest is rejected.

Unknown provider configuration fields are rejected.

Resource addresses

A resource address is three lowercase identifiers separated by dots:

provider.type.name

Example: matomo.goal.trial_started.

Each segment starts with a letter and may then contain lowercase letters, digits, or underscores. Duplicate addresses are rejected.

Resource references

Provider-neutral dependencies use a single-key $ref object:

resources:
  - address: matomo.trigger.trial_started
    attributes:
      type: customEvent
      event: trialStarted

  - address: matomo.tag.trial_started
    attributes:
      type: matomoAnalytics
      trigger:
        $ref: matomo.trigger.trial_started
      eventCategory: signup
      eventAction: trialStarted

The $ref value is always a logical Agoraform address, never a provider-native ID. Ordinary strings remain provider-owned values even if they happen to look like an address.

Agoraform validates references and builds a directed dependency graph. Missing references, self-references, and cycles fail before remote mutations.

At apply time, logical references are resolved to provider-native identities and computed outputs in dependency order. Those provider-native values are not written back into the manifest.

Resource attributes

resources[].attributes is provider-owned configuration. The core normalizes YAML types and understands $ref; providers validate the actual schema. Computed and read-only provider fields do not belong in configuration and must not produce changes merely because provider-native IDs differ.

See the manifest reference for every field documented in v0.3.0.