Google Tag Manager

<!-- versions:start -->

🎯 Version Requirements (June 2026)

Primary pins:

• GTM API: v2 (stable)
• googleapis (Node): 144.x
• google-api-python-client: 2.x
• Node.js: 24.x (Active LTS)
• Python: 3.14.x

Source of truth: STACK_VERSIONS.md — verified 2026-06-11

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. This is the single source of truth for Google Tag Manager API v2 operations: reading container state, making writes, publishing versions, and rolling back. Read the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Listing, creating, or updating GTM containers, workspaces, tags, triggers, or variables programmatically
• Publishing a workspace to live — requires the two-step create_version + publish flow
• Rolling back a GTM container to a previous version (two-step: create_version_from_old → publish)
• Auditing all tags in a container: list tags referencing a specific variable, find unused triggers
• Bulk-renaming or migrating variables via export-edit-import pattern
• Cloning a workspace for staging / QA before publish
• Diagnosing etag conflicts (409) on concurrent container edits
• Managing write quota (~25 write ops/min/container) and planning batch operations
• Setting up a service account or OAuth flow for GTM API access
• Finding account IDs and container IDs via API (accounts.list, containers.list)

Do not use this skill when

• You need GA4 event analytics (sessions, conversions, reports) — use google-analytics
• You need Google OAuth / Service Account credential setup — use google-cloud-auth
• You need to write data into GA4 via Measurement Protocol — use google-analytics
• You need Yandex.Metrica tag management — different provider; load yandex-metrica
• You need generic HTTP transport patterns (retries, backoff) — use httpx or nodejs
• You need GTM server-side container code (sGTM custom templates in JavaScript) — different domain; check gtm-server-side if that skill exists

Purpose

Google Tag Manager API v2 (https://tagmanager.googleapis.com/tagmanager/v2/) is the programmatic surface for managing GTM containers. It exposes a full hierarchy — Account → Container → Workspace → Tag/Trigger/Variable/Folder — with CRUD at every level, plus a publish workflow based on immutable, numbered Versions. Every write that modifies a live container must go through the two-step path: create an immutable Version checkpoint from the Workspace, then publish that Version; direct publish-without-checkpoint is not supported.

This skill is high-stakes because publishing incorrect tags to a live GTM container can instantly break analytics collection, fire unwanted pixels, or block consent flows for every visitor of the site. Rollback is possible but requires the two-step sequence described in references/rollback.md. Write operations consume a conservative per-container quota; exceeding it silently queues or drops changes. Etag-based optimistic concurrency is mandatory on updates to prevent one agent from stomping another's edits.

Capabilities

Authentication

GTM API uses standard Google OAuth 2.0 or a Service Account. The required scope for read-only access is https://www.googleapis.com/auth/tagmanager.readonly. For write operations (create, update, delete, publish) the scope is https://www.googleapis.com/auth/tagmanager.edit.containers. For publishing specifically the scope is https://www.googleapis.com/auth/tagmanager.publish. Service accounts must be granted access in the GTM Account/Container settings (not just IAM). Auth bootstrap is owned by google-cloud-auth.

Full reference: references/setup.md

Resource hierarchy

GTM resources form a strict parent-child tree: Account (one per Google account or organization) → Container (one per site/app) → Workspace (edit sandbox; default workspace always exists) → Tag/Trigger/Variable/Folder (leaf resources within a Workspace). Versions sit alongside Workspaces at the Container level and are immutable snapshots. Permissions are granted at the Account or Container level; a user with container-level access cannot see other containers in the same account.

Full reference: references/resources-hierarchy.md

Tags, Triggers, Variables CRUD

All three resource types follow the same REST pattern under a workspace path: list, get, create, update, delete. Tags reference trigger IDs in firingTriggerIds and blockingTriggerIds. Triggers evaluate conditions and fire tags. Variables resolve values (page URL, data layer values, cookie contents, etc.) that tags and triggers use. Updates require the current fingerprint (etag) in the request body to prevent concurrent-edit conflicts.

Full reference: references/tags-triggers-variables.md

Workspaces

A Workspace is the mutable edit surface inside a Container. The Default Workspace always exists; custom workspaces enable parallel development tracks. A Workspace stays in sync with the published version via the sync endpoint; conflicts (when the live version changed since the workspace was created) are surfaced as a mergeConflict list. getStatus shows all changes not yet in the live version.

Full reference: references/workspaces.md

Versions and publish

A Version is an immutable snapshot of a Container. The workflow to push changes live: (1) call workspaces:create_version on your workspace — this produces a numbered Version; (2) call versions/{versionId}:publish on that Version. The API does not support publishing a workspace directly. After publish, versions:live reflects the newly live state. Versions serve as the audit trail and rollback source.

Full reference: references/versions-publish.md

Rollback

Rollback is a two-step process: you cannot "reset to version N" directly. Step 1: call versions/{old_version_id}:create_version_from_old — this creates a new Version that is a copy of the target old Version. Step 2: call versions/{new_version_id}:publish on the freshly created Version. The previous live Version is preserved in history. In-flight workspace edits are not affected but may conflict with the rolled-back state.

Full reference: references/rollback.md

Etag-based concurrency

Every mutable GTM resource carries a fingerprint field. When two agents edit the same resource concurrently, the second write will receive 409 Conflict if the fingerprint has changed. Always: (1) GET the resource to obtain the current fingerprint, (2) include that fingerprint in the UPDATE body, (3) handle 409 by re-fetching and retrying.

Full reference: references/errors.md