/google-tag-manager

name: google-tag-manager
description: "[RU: gtm, тег менеджер, google tag manager, контейнер, теги, триггеры, переменные, публикация версии, откат] GTM API v2 full read + write — Account/Container/Workspace hierarchy, Tag/Trigger/Variable CRUD, version create + publish + rollback (two-step). Use when: gtm, tag manager, containers, workspaces, publish, rollback, etag concurrency, write quotas. SKIP: gtm server-side container code (→gtm-server-side if it exists, else omit); GA4 measurement protocol (→google-analytics); legacy ga.js."
stacks:
  - google-tag-manager
  - marketing-tech
  - nodejs
  - python
tags:
  - google
  - gtm
  - tag-manager
  - containers
  - workspaces
  - publish
  - rollback
  - marketing
source: vechkasov-global-skills
risk: high-stakes

<!-- 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](../../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](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](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](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