Quick Start

This walkthrough uses Agoraform v0.6.0. Choose the provider workflow you can reach, then run the same 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. agoraform destroy is a separate explicit teardown step.

Option A: Meta website conversion campaign

The primary v0.6 example manages a complete paused website conversion campaign in Meta Ads:

meta.pixel.website binds an existing Pixel/Dataset event source
meta.custom_conversion.trial_started is a START_TRIAL website Custom Conversion
meta.campaign.website_acquisition is a paused OUTCOME_SALES auction campaign
meta.ad_set.instagram_trial is a paused ad set with daily budget, website conversion optimization, and typed Instagram placement targeting
meta.ad_creative.instagram_trial references externally prepared Page, Instagram, and image identifiers
meta.ad.instagram_trial binds the ad set to the creative

For an interactive Bash session, read -s avoids placing typed secrets in shell command history:

export META_AD_ACCOUNT_ID=act_123456789012345

read -rsp "Meta access token: " META_ACCESS_TOKEN; echo
export META_ACCESS_TOKEN

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

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

cp examples/meta-website-campaign/agoraform.yaml agoraform.yaml

Replace the placeholder pageId, instagramUserId, imageHash, destinationUrl, and pixel name with values for your account before applying. The tagged manifest uses no access tokens.

Then:

agoraform validate
agoraform plan
agoraform apply
agoraform plan

Agoraform does not install browser Pixel code, upload media bytes, or emit fbq events. Your website must emit the event named in the Custom Conversion rule (for example StartTrial).

To tear down the managed graph:

agoraform destroy

Destroy removes ads, ad sets, creatives, custom conversions, and campaigns in reverse dependency order. The Pixel/Dataset remains provider-owned and stays bound in state.

See the tagged Meta website conversion campaign example for verification, import, destroy ordering, and Ads Manager checks before enabling delivery.

Option B: Matomo + Google Ads lifecycle

The primary v0.5 example, still valid in v0.6.0, manages a website trialStarted conversion across Matomo Tag Manager and Google Ads:

an Agoraform-managed Matomo container, Matomo Configuration variable, Data Layer variable, and custom-event trigger
a Google Ads website SIGNUP conversion action and account-default SIGNUP / WEBSITE goal biddability
a Matomo Google Ads conversion tag that consumes conversionId and conversionLabel through { $ref, output }
declarative publication to live

Complete Google Ads setup first. Then:

export MATOMO_URL=https://matomo.example.com
export MATOMO_SITE_ID=1
export GOOGLE_ADS_CLIENT_ID=replace-with-your-oauth-client-id
export GOOGLE_ADS_CUSTOMER_ID=1234567890

read -rsp "Matomo API token: " MATOMO_TOKEN_AUTH; echo
export MATOMO_TOKEN_AUTH
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

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

See the tagged Matomo + Google Ads lifecycle example for verification, import, the external-container variant using MATOMO_CONTAINER_ID, and exact destroy ordering.

Option C: Google Ads Search campaign

The primary v0.4 example, still valid in v0.6.0, manages a complete paused Search campaign graph:

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

See the tagged Google Ads Search example for verification, safe enablement, immutable-field behavior, and dependency-ordered import.

Option D: Matomo conversion tracking (external container)

The primary v0.2 example, still valid in v0.6.0, manages a complete trialStarted conversion flow inside an existing container selected by MATOMO_CONTAINER_ID:

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

See the tagged Matomo conversion example.

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.