--- name: gtm-container-management description: Builds and governs a Google Tag Manager container so tags deploy cleanly and predictably, with one naming grammar, data-layer triggers instead of brittle DOM selectors, no duplicate tags, consent initialisation ordered first, and a human gate on publishing. Use when the request mentions Google Tag Manager, GTM, a container, tags, triggers or variables, the data layer or dataLayer, a Custom HTML or Custom JavaScript tag, GTM Preview, workspaces or versions, publishing a container, "my tag is not firing", duplicate tags, or server-side GTM. Do NOT use for designing the event taxonomy (event-tracking-plan), configuring the GA4 property itself (ga4-measurement-setup), configuring consent signals (consent-mode-tracking), validating that tags fire correctly (analytics-qa-validation), ad-platform conversions and the Conversions API (conversion-tracking-capi), or analysing the collected data (funnel-analysis, cohort-retention-analysis). license: CC BY 4.0. Free to use and adapt with credit to Afeez Adebayo. metadata: author: Afeez Adebayo website: https://afeezadebayo.com linkedin: https://www.linkedin.com/in/afeez-adebayo/ source: https://afeezadebayo.com/skills-md/data/analytics-tracking/gtm-container-management/ category: data subcategory: analytics-tracking version: 1.0.0 created: 6 November 2026 updated: 6 November 2026 --- # GTM container management A tag manager container collects tags until nobody can say what fires, on what, or why. A trigger built on a CSS selector stops working the day the site is redesigned. A second Google tag on one template doubles every event it touches. And one click on Submit pushes all of it to production. This skill makes an AI agent build and change a container the way a careful engineer changes shared infrastructure: with one naming grammar, triggers read from the data layer rather than the page, one tag per job, consent set before anything fires, and a human asked before the container is published. The job is the container as the place tags live and deploy, not the data they carry or the property they feed. The event names and properties come from the tracking plan, the analytics property is configured elsewhere, consent signals have their own skill, and proving the tags fire is a separate job. This skill keeps the container clean, legible and safe to publish, and hands each of those neighbouring jobs to the sibling skill that owns it. ## When to use this skill, and when not to Use this skill to set up a new container, add or change tags, triggers and variables, impose a naming convention, clean up a container nobody can read, debug a tag that will not fire, or review a container before it is published. It fires on Google Tag Manager, GTM, containers, tags, triggers, variables, the data layer, Custom HTML or Custom JavaScript tags, GTM Preview, workspaces and versions, publishing, "my tag is not firing", duplicate tags, and server-side GTM. Do not use it to decide which events and properties exist, which is the sibling `event-tracking-plan`. Do not use it to configure the GA4 property, its dimensions or retention, which is `ga4-measurement-setup`. Do not use it to configure consent signals and modes, which is `consent-mode-tracking`, though this skill makes sure the consent step is ordered correctly. Do not use it to prove the tags fire once with the right data, which is `analytics-qa-validation`. Do not use it for ad-platform conversions and the Conversions API, which is `conversion-tracking-capi`. If there is no agreed data-layer and event spec to build against, get one first; a container built on guesses about what the site pushes is a container that breaks on the next deploy. ## Inputs the agent must have before starting Ask for these in one message, and do not assume them: 1. The list of tags to deploy and the events that trigger them, from the tracking plan. Without it there is nothing to build to. 2. Access to the container, and who holds Publish rights, because publishing is the one irreversible step. 3. The data-layer specification: the events and keys the site pushes, or confirmation that developers will add them. DOM scraping is the fallback, not the plan. 4. The consent setup and the market, so the consent step is ordered before tags that need it (detailed configuration is `consent-mode-tracking`). 5. Whether a server-side container is in use, because consent and some tags behave differently there. 6. The environments available (staging, preview, production), so changes are tested before they reach users. If this is a debugging request rather than a build, scope it to the failing tag and its trigger, and do not reorganise the whole container around one bug. ## Workflow ### Step 1. Fix the naming grammar before building anything A container is only as maintainable as its names. Set one grammar for every asset and apply it to what already exists: - Tags: type, then grouping, then an optional subgroup, then the action, for example `GA4 - Event - Add to cart` or `Google Ads - Remarketing - Checkout`. - Triggers: type, then the user action, then an optional scope, for example `Custom Event - add_to_cart` or `Scroll - 75% - EU`. - Variables: type, then an optional subtype, then a description, for example `DLV - ecommerce.value` or `Constant - GA4 Measurement ID`. Use consistent casing and a single delimiter. Decision rule: if a name does not tell you the platform and the purpose at a glance, rename it before you add anything near it. ### Step 2. Build on the data layer, not the page The data layer is the contract between the site and the container. Define the events and keys the site will push (the event spec comes from `event-tracking-plan`), have developers push them, and create Data Layer variables to read them. Decision rule: trigger on a data-layer custom event, not on a DOM or CSS selector, wherever you can. A selector-based trigger reads the page's markup and breaks silently the next time the page is restyled; a custom-event trigger keeps working because it depends on a contract, not a layout. Never push personal data into the data layer; if an identifier is needed, hash it first. ### Step 3. Build tags with built-in parts first Reach for built-in variables and triggers before Custom HTML or Custom JavaScript. Custom code is harder to audit, easier to break, and a common home for mistakes. - One tag per destination per event. Before adding a tag, search the container for one that already does the job, because a duplicate Google tag or a second GA4 configuration is the most common cause of doubled events. - Custom JavaScript variables and Custom HTML tags must be written in ES5; GTM's sandbox does not run newer syntax. Regular expressions use RE2, so an inline flag such as `(?i)` sets case-insensitivity rather than a trailing flag. - Do not hardcode secrets such as API keys in a tag. Put them in constant variables and restrict who can edit the container. ### Step 4. Order consent initialisation first A consent default must be set before any tag that depends on consent fires. In GTM that means the consent step runs on the Consent Initialisation stage or an all-pages trigger ahead of the tags, and each tag carries the right consent checks. The detailed configuration, the basic-versus-advanced choice, regions and persistence, belongs to `consent-mode-tracking`; this step only makes sure the ordering is right and no measurement tag jumps the queue. For a server-side container, there is no built-in consent mode: the server depends on the web container passing the consent state, for example through the GCS parameter (`G100` denied, `G111` granted) or a consent event. Treat consent checks on server tags as obligatory, the same as on the web. ### Step 5. Work in a workspace, test in Preview, version every change Make changes in a workspace of their own, one per project or workstream, so parallel work does not collide. Then test in Preview and a tag assistant before anything is published: each tag fires on the right trigger, exactly once, with the right variables populated, and not before consent. Walk the real user journeys, not just the home page. Name and describe every version with what changed and why, and keep a running changelog. Version history is what lets you compare and revert, so an unnamed version is a lost audit trail. ### Step 6. Publish behind a human gate, with least privilege Publishing pushes the whole workspace to production at once, and the data it changes is not recoverable for the period before anyone notices and reverts. So treat publishing as an irreversible action: get explicit human confirmation before you publish, and never publish on the agent's own initiative. Remember that Save is not Submit; changes only go live on Submit and Publish. Limit who can publish. GTM container roles run No access, Read, Edit, Approve and Publish; Editors can build without publishing, and an approver or lead publishes. After a publish, confirm the container is live with Preview off, then hand the job of proving each tag fires once with the right data to `analytics-qa-validation`. ## Worked example A container has drifted. Two GA4 configuration tags sit on different templates and fire `page_view` twice for checkout traffic, and several triggers use CSS selectors that stopped matching after a redesign, so `add_to_cart` quietly went dark three weeks ago. The agent renames every tag, trigger and variable to the grammar so the duplicates are obvious at a glance. It removes the second GA4 configuration tag, which fixes the doubled `page_view`. It replaces the selector-based triggers with custom-event triggers reading a `add_to_cart` push the developers now add to the data layer, so the next redesign will not break them. It moves all of this into a named workspace, tests in Preview, and confirms each tag fires once, after consent, with the right variables. It writes a version description listing the two fixes, then stops and asks for sign-off rather than publishing itself. After the human publishes, it hands the firing checks to `analytics-qa-validation`. The headline is that the container's two worst problems, a duplicate tag and brittle triggers, were both invisible until the names made them visible. ## Templates you can use verbatim Naming grammar: ``` Tags: - - [subgroup] - e.g. GA4 - Event - Add to cart Triggers: - - [scope] e.g. Custom Event - add_to_cart Variables: - [subtype] - e.g. DLV - ecommerce.value Rule: a name must state platform and purpose at a glance, or it gets renamed. ``` Data-layer push (ES5, pushed by the site before the tag needs it): ``` window.dataLayer = window.dataLayer || []; window.dataLayer.push({ event: 'add_to_cart', ecommerce: { currency: 'USD', value: 29.0, items: [{ item_id: 'SKU123', quantity: 1 }] } }); ``` Pre-publish checklist (run in Preview before Submit): ``` [ ] Every asset follows the naming grammar [ ] Triggers use data-layer custom events, not DOM/CSS selectors [ ] One tag per destination per event; no duplicate Google tag or GA4 config [ ] Consent initialisation fires before any consent-gated tag; tags have consent checks [ ] Each tag fires once, on the right trigger, with the right variables, after consent [ ] Custom code is ES5; regex is RE2; no hardcoded secrets (use restricted constants) [ ] No PII pushed to the data layer (hash identifiers) [ ] Change is in a named workspace; version has a description of what changed and why [ ] Human sign-off obtained before Submit and Publish ``` Version description template: "What changed: [tags/triggers added, changed, removed]. Why: [the reason or ticket]. Tested: [journeys walked in Preview]. Risk: [what to watch after publish]." ## Failure modes and anti-patterns 1. Triggers built on DOM or CSS selectors. You spot it when a tag that worked stops firing after a site change, with no container edit. Fix it by triggering on data-layer custom events the site pushes, so the trigger depends on a contract rather than markup. 2. A duplicate Google tag or GA4 configuration. You spot it when a metric reads roughly double for some traffic. Fix it by keeping one tag per destination per event and auditing the container for an existing tag before adding another. 3. Publishing without testing or sign-off. You spot it when production breaks after a change, or when a change never went live because someone pressed Save, not Submit. Fix it by testing in Preview, writing a named version, and gating Submit on explicit human confirmation. 4. Custom HTML and JavaScript everywhere. You spot it when the container is full of bespoke code, ES6 syntax fails in the sandbox, and nobody can audit what runs. Fix it by using built-in variables and triggers first, writing any custom code in ES5, and storing secrets in restricted constant variables. 5. Personal data or secrets in the container. You spot it when an email or token appears in a data-layer push, or an API key is pasted into a Custom HTML tag. Fix it by never pushing personal data (hash identifiers), and moving secrets into constant variables with restricted access. ## Quality bar for the container Before handing over, confirm every item: - Every tag, trigger and variable follows one naming grammar that states platform and purpose. - Triggers read data-layer custom events rather than DOM or CSS selectors wherever possible. - There is one tag per destination per event, with no duplicate Google tag or GA4 configuration. - Consent initialisation is ordered before any consent-gated tag, and tags carry the right consent checks. - Changes were made in a named workspace, tested in Preview across real journeys, and saved as a version with a description. - Publishing was gated on explicit human sign-off, and Publish rights are limited to the people who need them. - No personal data is pushed to the data layer and no secrets are hardcoded; custom code is ES5 and regex is RE2. - For a server-side container, the consent state is passed from the web container and server tags check it. - Any version-dependent detail (role names, sandbox APIs, template fields) was checked against current documentation. ## Tool-specific appendix ``` Google Tag Manager specifics (verify version-dependent details before relying on them) - Container roles: No access, Read, Edit, Approve, Publish. Editors build; approvers or leads publish. - Save vs publish: Save keeps a draft; changes go live only on Submit and Publish, to all users at once. - Custom code: Custom HTML tags and Custom JavaScript variables must be ES5; the sandbox rejects newer syntax. - Regex: GTM uses RE2, so use an inline flag like (?i) for case-insensitivity, e.g. (?i)^/checkout. - Triggers: prefer Custom Event triggers reading the data layer over Click/Element triggers on CSS selectors. - Duplicate tags: more than one Google tag or GA4 configuration per page doubles events; keep one per job. - Consent: a consent default must run on Consent Initialisation before consent-gated tags; Google tags have built-in consent checks, other tags need them added. Detailed setup is consent-mode-tracking. - Server-side: no built-in consent mode; the server reads consent passed from web GTM (GCS parameter G100 denied / G111 granted, or a consent event). A CMP custom event is the more reliable signal. - Testing: GTM Preview and a tag assistant show which tags fired and what they read; walk real journeys. ``` ## Sources - Analytify, Google Tag Manager best practices (naming scheme with type prefixes, one workspace per project, named and described versions, limiting Publish rights, built-in variables first, auditing for duplicate and misfiring tags, Save versus Submit and Publish). Last verified 6 November 2026. - Precis, GTM naming convention guide (component order for tags, triggers and variables, and reasoning). Last verified 6 November 2026. - Google Tag Manager Claude skills by wookstar and by other authors (ES5 in Custom JavaScript and Custom HTML, GTM's RE2 regex and the (?i) inline flag, never push PII to the data layer); these are the implementations this skill improves on by adding explicit decision rules, versioned publishing and a human gate. Last verified 6 November 2026. - Stape, consent settings for server-side GTM (server GTM has no built-in consent mode; consent is passed from web GTM via the GCS parameter, a Data Tag consent state, or a CMP custom event, with the custom event the more reliable). Last verified 6 November 2026. - Google, Consent Mode guide (a consent default must be set before measurement tags fire). Last verified 6 November 2026; consent parameters are version-dependent, so re-check the documentation. - Related skills: event-tracking-plan (the event spec the data layer carries), ga4-measurement-setup (the property the GA4 tags feed), consent-mode-tracking (configuring the consent signals), analytics-qa-validation (proving each tag fires), conversion-tracking-capi (ad-platform conversions).