Quick Start

This walkthrough uses Agoraform v0.3.0. Choose the provider you can reach, then run the same four commands.

validate -> plan -> apply -> plan

Review the first plan before applying. The final plan should report No changes. when desired configuration, local state, and remote state are unchanged.

Option A: Google Ads conversion measurement

The primary v0.3 example manages a website Trial Started conversion:

googleads.conversion_action.trial_started as a SIGNUP website conversion
googleads.customer_conversion_goal.signup so SIGNUP / WEBSITE is biddable as an account-default optimization goal
a logical $ref so the conversion action exists before goal reconciliation

Agoraform manages Google Ads configuration only. Website tags, Google Tag Manager, and application event emission stay outside the provider. After apply, use the conversion ID and conversion label from Google Ads when configuring those external tools.

Complete Google Ads setup first. Then, for an interactive Bash session, read -s avoids placing typed secrets in shell command history:

export GOOGLE_ADS_CLIENT_ID=replace-with-your-oauth-client-id
export GOOGLE_ADS_CUSTOMER_ID=1234567890

read -rsp "Google Ads developer token: " GOOGLE_ADS_DEVELOPER_TOKEN; echo
export GOOGLE_ADS_DEVELOPER_TOKEN
read -rsp "Google Ads OAuth client secret: " GOOGLE_ADS_CLIENT_SECRET; echo
export GOOGLE_ADS_CLIENT_SECRET
read -rsp "Google Ads refresh token: " GOOGLE_ADS_REFRESH_TOKEN; echo
export GOOGLE_ADS_REFRESH_TOKEN

Do not substitute literal secret values into those prompt commands. On automated systems, inject the GOOGLE_ADS_* secrets from your secret manager. You can also store them in .agoraform.env.

Copy the included example from a v0.3.0 checkout or release archive:

cp examples/googleads-conversion/agoraform.yaml agoraform.yaml

apiVersion: agoraform.io/v1alpha1
providers:
  googleads: {}
resources:
  - address: googleads.conversion_action.trial_started
    attributes:
      name: Trial Started
      category: SIGNUP
      value: 0
      count: ONE
      primaryForGoal: true

  - address: googleads.customer_conversion_goal.signup
    attributes:
      category: SIGNUP
      origin: WEBSITE
      biddable: true
      conversionAction:
        $ref: googleads.conversion_action.trial_started

Then:

agoraform validate
agoraform plan
agoraform apply
agoraform plan

The conversion action is created. The customer conversion goal is created by Google Ads; Agoraform adopts or updates it and never attempts unsupported create or delete operations.

See the tagged Google Ads conversion example for Google Ads verification, conversion identifiers for website tags, and import of equivalent manually configured conversion measurement.

Option B: Matomo conversion tracking

The primary v0.2 example, still valid in v0.3.0, manages a complete trialStarted conversion flow:

a Data Layer variable that reads userId
a Custom Event trigger for trialStarted
a Matomo Analytics event tag
logical references that force the variable and trigger to exist before the tag
declarative publication to a Matomo Tag Manager environment

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

export MATOMO_URL=https://matomo.example.com
export MATOMO_TOKEN_AUTH=replace-with-your-api-token
export MATOMO_SITE_ID=1
export MATOMO_CONTAINER_ID=replace-with-your-container-id

cp examples/matomo-conversion/agoraform.yaml agoraform.yaml

apiVersion: agoraform.io/v1alpha1
providers:
  matomo:
    publish: true
    environment: live
resources:
  - address: matomo.variable.user_id
    attributes:
      type: dataLayer
      key: userId
      name: Trial user ID

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

  - address: matomo.tag.trial_started
    attributes:
      type: matomoAnalytics
      name: Track trial started
      trigger:
        $ref: matomo.trigger.trial_started
      eventCategory: trial
      eventAction: started
      eventName:
        $ref: matomo.variable.user_id

agoraform validate
agoraform plan
agoraform apply
agoraform plan

With publication enabled, the plan makes the potential container publication visible before mutation. apply performs draft resource changes in dependency order and only then creates and publishes a container version when the converged draft still differs from the published environment. Repeated unchanged apply must not create duplicate container versions.

After the Matomo Tag Manager container snippet has initialized window._mtm, the application emits:

window._mtm.push({
  event: "trialStarted",
  userId: "..."
});

Use a stable, non-secret, non-email identifier for userId.

Default manifest path

Commands read agoraform.yaml in the current directory unless you pass -f / --file or a positional path:

agoraform validate
agoraform validate -f path/to/manifest.yaml
agoraform validate path/to/manifest.yaml

Specify a manifest as an argument or with --file, not both.

Quick Start

Option A: Google Ads conversion measurement

Option B: Matomo conversion tracking

Default manifest path

Next