<< All versions

Skill v1.0.0

currentLLM-judged scan90/100
vkirill/claude-lane-stack/google-tag-manager
──Details
PublishedOctober 22, 2026 at 04:31 PM
Content Hashsha256:e3121a63dabcead7...
Git SHA7d292d808dba
──Files
Files (1 file, 12.3 KB)
SKILL.md12.3 KBactive
SKILL.md · 170 lines · 12.3 KB

version: "1.0.0" 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 — 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.

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.

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.

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

Errors and quotas

GTM API returns standard Google error JSON. Key codes: 401 (token expired), 403 (missing scope or not granted access on container), 409 (etag/fingerprint conflict on concurrent edit), 429 (write quota ~25 ops/min/container), 500/503 (transient). Exponential backoff with jitter is required on 429 and 5xx.

Full reference: references/errors.md

Real automation examples

Five-to-eight concrete automation recipes: create GA4 event tag, add consent-aware trigger, bulk-rename variables, rollback to version N-1, list tags referencing a specific variable, find unused triggers, clone workspace for staging.

Full reference: references/cookbook.md

Behavioral Traits

  • Always obtain the live versionId before any publish to enable rollback if needed
  • Always read the resource fingerprint before an update — include it in the body to prevent 409
  • Always create a Version (create_version) before publish — no workspace-direct publish path exists
  • Treat write quota as a real constraint: batch related changes in one workspace, avoid per-item loops that fire 25+ writes/min
  • For rollback: never auto-roll back. Present the target version summary to the user, get confirmation, then execute the two-step sequence
  • Treat 409 as expected in multi-agent scenarios; re-GET, merge, retry
  • For bulk operations: list all resources first, filter locally, then write — minimizes API calls and quota consumption

Important Constraints

  • NEVER publish to live without calling `create_version` first — create_version is the safety checkpoint; without it there is no version to roll back to
  • ALWAYS capture the current `liveVersionId` before publish — store it so rollback can target the correct old version
  • Rollback requires a confirmation prompt — never auto-rollback — show the user the target version (name, description, creation time) and ask for explicit approval before executing the two-step sequence
  • NEVER send an UPDATE or DELETE without including the current fingerprint in the request body — omitting it risks stomping concurrent edits (409 is the best outcome; silent data loss is the worst)
  • NEVER exceed the write quota (~25 ops/min/container) without exponential backoff — plan bulk operations with delays
  • NEVER commit service account key files to git — use environment variables or a secrets manager
  • ALWAYS verify the service account or OAuth user is granted access at the GTM Account or Container level in the GTM UI, not just at Google Cloud IAM level
  • ALWAYS enable the Tag Manager API in the Google Cloud Console project — a valid key file alone is insufficient
  • Rollback is a TWO-STEP operation: create_version_from_old → publish — there is no single "revert" endpoint

Related Skills

  • google-cloud-auth — OAuth 2.0 user flow, Service Account JWT, ADC, scopes catalog, invalid_grant recovery (required before any GTM API call)
  • google-analytics — GA4 reporting; pair with GTM for the full analytics instrumentation story
  • google-search-console — GSC search data; often used alongside GTM in the same site analytics stack
  • nodejs — Node.js runtime patterns for googleapis library (google.tagmanager('v2'))
  • python — Python runtime patterns for google-api-python-client (build('tagmanager', 'v2', ...))
  • httpx — Python HTTP transport for raw REST calls with bearer tokens
  • postgresql — persistence for version snapshots, audit logs, rollback history

API Reference

TopicFile
Auth (OAuth + Service Account), discover Account/Container IDs, curl + Node + Python initreferences/setup.md
Account → Container → Workspace → Tag/Trigger/Variable/Folder hierarchy, permissions modelreferences/resources-hierarchy.md
Tags, Triggers, Variables CRUD — types catalog, JSON examplesreferences/tags-triggers-variables.md
Workspace lifecycle — default/custom, sync, conflict resolution, getStatus diffreferences/workspaces.md
Version create, publish, get_live, undelete — audit trailreferences/versions-publish.md
Rollback recipe (two-step) — risks, confirmation pattern, code walkthroughreferences/rollback.md
Errors 401/403/409/429/500, etag conflicts, retry policy with exponential backoffreferences/errors.md
Cookbook — 7 real automations end-to-endreferences/cookbook.md
All versions