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 and Meta have no non-secret YAML fields in v0.6.0; empty providers.googleads: {} and providers.meta: {} blocks are accepted and still validate 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 $ref object containing a logical Agoraform address. Address-only references stay a single-key map:

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.

An optional output selector consumes one declared non-sensitive named output from the referenced resource, including across providers:

conversionId:
  $ref: googleads.conversion_action.trial_started
  output: conversionId

A reference without output still resolves to the full runtime binding (provider-native identity plus computed outputs). A reference with output resolves to that one value. Unknown, sensitive, unavailable, and wrong-kind outputs fail before the dependent mutation.

Agoraform validates references and builds a directed dependency graph. Missing references, self-references, and cycles fail before remote mutations. Cross-provider output references create the same kind of dependency edge.

At apply time, logical references are resolved 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.6.0.