Matomo

Overview

The Matomo provider is Agoraform’s first production provider. v0.1.0 introduced analytics goals. v0.2.0 added Matomo Tag Manager variables, triggers, tags, and declarative container publication. v0.3.0 retains that Matomo surface unchanged.

The Agoraform CLI remains provider-neutral. There is no Matomo-specific publish command.

Source at tag v0.3.0.

Supported capabilities

• matomo.goal — read, create, update, import
• matomo.variable — Data Layer variables; read, create, update, import
• matomo.trigger — Custom Event triggers; read, create, update, import
• matomo.tag — Matomo Analytics event tags; read, create, update, import
• Declarative Tag Manager publication through providers.matomo.publish and providers.matomo.environment
• Logical $ref dependencies with prerequisite-first plan and apply

One Tag Manager container is configured at a time through MATOMO_CONTAINER_ID.

Prerequisites

• A Matomo instance you are allowed to change
• For goals: a numeric site ID
• For Tag Manager: an existing container, and a Matomo Configuration variable already in that container before you manage matomo.tag resources
• An API token allowed to manage the site/container and, if publishing, to publish to the target environment

Authentication / setup

Credentials and connection details stay outside the manifest. Set environment variables or use .agoraform.env.

Environment variables

MATOMO_URL            required   Matomo base URL, for example https://matomo.example.com
MATOMO_TOKEN_AUTH     required   API token
MATOMO_SITE_ID        required for managed Matomo site resources
MATOMO_CONTAINER_ID   required for Tag Manager resources and publication

Tokens never belong in the manifest, logs, plan output, or local state.

Supported resources

matomo.goal

- address: matomo.goal.trial_started
  attributes:
    name: Trial Started
    matchAttribute: event_action
    pattern: trialStarted

Attribute	Required	Description
name	yes	Goal name; immutable once local state binds the resource
matchAttribute	yes	Goal matching mode such as event_action, url, or manually
pattern	unless manually	Value to match
patternType	no	contains (default), exact, or regex; numeric modes use provider defaults

Agoraform preserves unmanaged Goal fields during updates. Provider-native goal IDs are stored in local state. Manifests that still contain idGoal are rejected.

matomo.variable

- address: matomo.variable.user_id
  attributes:
    type: dataLayer
    key: userId
    name: User ID

type: dataLayer and key are required. name is optional and defaults to key. Provider-native IDs, status, and version metadata are computed, not desired attributes. Updates preserve unmanaged Matomo fields.

Agoraform may encounter other, unmanaged Matomo variable types while reading a container. Their scalar and structured parameter values are tolerated so they do not prevent managed Data Layer variables from being planned or applied. v0.2.1 fixed structured Matomo variable parameter decoding; that fix is present in v0.3.0.

matomo.trigger

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

type: customEvent and event are required. name is optional and defaults to event. Updates preserve unmanaged description/conditions.

matomo.tag

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

The target container must already contain a Matomo Configuration variable. v0.3.0 does not manage MatomoConfiguration variables declaratively.

Attribute	Required	Notes
type	yes	v0.2 supports matomoAnalytics
trigger	yes	$ref to a managed matomo.trigger
eventCategory	yes	Literal or supported variable $ref
eventAction	yes	Literal or supported variable $ref
eventName	no	Literal or supported variable $ref
eventValue	no	Numeric literal/string or supported variable $ref
name	no	Defaults from eventAction when possible

Import reconstructs logical trigger/variable $refs when related remote objects are already in local state. Import prerequisites first.

Example manifest

See the quick start Matomo example and the tagged conversion example.

Publication

providers:
  matomo:
    publish: true
    environment: live

publish defaults to false. environment defaults to live when publication is enabled. Omitting providers.matomo leaves publication disabled.

When publication is required, plan shows:

> matomo.container.main: publish -> live [conditional]

apply first reconciles all planned draft resources. Only after those mutations succeed does it recheck the converged draft, create a container version if needed, and publish it to the configured environment.

Before version creation, Agoraform verifies that the credentials can publish to the configured environment using TagManager.getAvailableEnvironmentsWithPublishCapability. Unknown environments or insufficient publish capability fail before the version-creation mutation.

Publication comparison ignores provider-native IDs and computed version metadata. Behavioral tag status (active versus paused) is part of the comparison.

An empty, JSON null, unreadable, oversized, or otherwise unrecognizable publish response is not treated as success.

Known limitations

• One Matomo Tag Manager container at a time (MATOMO_CONTAINER_ID)
• Tag Manager types are limited to Data Layer variables, Custom Event triggers, and Matomo Analytics event tags
• MatomoConfiguration is a prerequisite, not a managed resource
• No provider-specific agoraform publish command
• Rollback, scheduled publication, approval workflows, and multi-container orchestration are not implemented
• apply does not delete remote resources