What a migration has to avoid
Google's Tag Manager overview describes the product as a way to manage tags without editing site code each time. A migration changes where every tag lives, and in doing so it can change what each tag counts. Five risks cover almost every migration that goes wrong.
| Risk | How it happens | Guard |
|---|---|---|
| A gap | The old code is removed in one release and the container tags go live later, or a template is missed | Release the container and remove the code together; install the container on every template first |
| A double count | The new tag goes live while the old code is still on some pages, cached pages or a separate checkout theme | Cut over per tag; compare counts daily; search every template for the old code |
| A changed definition | The old tag fired on a page view and the new one on a data layer event, or read a different value | Write the contract first; compare payloads in preview before the switch |
| A consent regression | Old tags had hand-written consent checks, or none, and the new ones are configured differently | Set consent on every tag in the container and test both branches |
| Lost early tags | Something that must run before the container, such as a consent default, is moved into it | Decide which tags stay in code before rebuilding anything |
The comparison guide puts the double count plainly: the same tag in the template and in the container is the standard way to count everything twice. Every step below exists to prevent one of these five.
Before you start
- Access to the site's code or CMS and a developer for the template changes, plus a staging site where releases can be rehearsed.
- A container in the business's own account, with publish rights held by the person running the migration; the containers and workspaces guide explains why ownership matters and how workspaces, versions and environments work.
- Preview mode and the browser's developer tools, used as the debugging tutorial describes, including the network panel.
- The tracking plan and the list of accounts that receive data: analytics properties, ad accounts, affiliate and review platforms.
- An agreed split with engineering on what stays in code, from the comparison guide's hybrid patterns.
- The systems of record: the order or lead system's daily counts, so the migration is judged against the truth rather than against the old tags.
Inventory every tag that runs
Find every script that sends data anywhere. Read the page source of each template, head and body, including checkout, account, error and campaign landing pages. Open the network panel on the key pages and list every request to a third party. Check the CMS's script fields, theme settings and plugins, and the e-commerce platform's native integrations, which can send purchases without any visible script. Ask each vendor account which pages it receives data from. For each tag, record the vendor, its purpose, its account identifier, the pages it runs on, what it sends and when, who owns it in the business, and its consent category. The inventory is the migration's checklist and, afterwards, the start of the vendor register.
Decide keep, move or retire
Give every inventory row one of three decisions. Retire tags for vendors the business no longer uses, duplicates and anything nobody will own; a migration is the cheapest moment to remove them. Keep in code the short list the comparison guide describes: anything that must run before the container, such as a consent default that has to precede a hard-coded Google tag, and anything engineering treats as part of the product. Move everything else, usually the analytics, advertising and marketing tags. Record the reason next to each decision. Tags marked to keep become the exceptions list, so nobody re-adds them to the container later because they did not know they were already there.
Install the container on every template
Install the container snippet on every template before any tag moves, with the data layer declared above it. The containers guide describes the two parts, a script high in the head and a fallback immediately after the opening body tag, and warns that a container missing from the pages where conversions happen is the commonest installation fault. If the CMS offers a plugin, check what it outputs: some add the snippet twice, place it late or inject their own data layer. If the Google tag stays hard-coded for now, the consent default must be hard-coded above it, as the consent mode guide explains. Published empty, the container changes nothing, which makes this a safe first release.
Write the data layer contract
Hard-coded tags often read values the template printed into the script: the order total, the product identifier, the page type. Do not reproduce that by scraping the page from the container. Instead, have the developers push the same values to the data layerA structured object on a web page that passes values to a tag manager for tags to use., at the moment the data layer guide sets out: context before the snippet, events when the action is true. Write each push into the contract table with its keys, types and consumers. Where an old tag fired on a page view of a thank-you page, decide whether the new tag should fire on a confirmed event instead, and record the change of definition so the comparison later expects it.
Rebuild each tag in a workspace
Work in one workspace per group of related tags, so each can be reviewed and released on its own. Rebuild each tag from a template where one exists, with account identifiers in constants, values from data layer variables and consent settings filled in. Name it by the container's convention and put the inventory row's details in its notes. Then compare it with the old tag in preview: on the same page, the network panel shows the old hard-coded request and the new container request side by side, which is the quickest way to see that the event, the identifiers and the values match. Preview runs the workspace draft in your browser only, so the comparison costs nothing in live data.
Choose the cut-over for each tag
Each tag needs one of two cut-overs. Switch in one release: the container tag goes live at the moment the old code is removed, which suits tags whose payload preview has already proved identical. Test destination first: the container tag sends to a test property, a test dataset or a separate account for a few days while the old tag keeps sending to the real one, then the destination is switched in the release that removes the old code; this suits tags whose definition changed, or whose counts the business relies on for bidding. The containers guide describes the environment variable that lets one container send staging traffic to a test property and live traffic to the real one. Never point both at the same destination.
Release the container and remove the old code together
The gap and the double count both come from the two changes landing at different times. Rehearse on staging: publish the container version to the staging environment, deploy the template release there, and walk the key journeys in preview. For production, one dependable technique is a release flag: the new templates push a key such as
tags_migrated: truein their context push, and every moved tag carries an exception trigger that blocks it when the flag is absent. The container can then be published first, and each tag starts firing on exactly the pages the new release serves. The flag closes the timing gap; it cannot remove old code the release missed, which is what the next step's comparison catches. Remove the flag condition once the release is complete everywhere.Compare counts with the period before
For each moved tag, compare daily counts with the same days before the move and with the system of record: page views, purchases, leads, each ad platform's conversions. A step up points at a double count, usually old code left on a template the release missed, cached pages, or a separate checkout theme. A step down points at a gap: a template without the container, a trigger that does not match, or consent configured more strictly than before. Expected changes, such as a conversion now counted on a confirmed event, should move by the amount the earlier definition overcounted. The data quality guide describes the monitoring that keeps watching after the comparison ends.
Document and hand over
Close the migration in writing. Update the tracking plan with every event and its source. Make sure each tag in the container has its notes and folder, and every version a note. Publish the exceptions list of tags that stayed in code, with reasons. Turn the inventory into the vendor register the governance guide describes, with owners, consent categories and review dates. Confirm who holds publish rights. Then hand the container to the routine the governance guide and the GTM container publish checklist describe, so the next change is made the same careful way.
A migration, tag by tag (illustrative)
Hazelvane Garden Supplies empties its templates
Hazelvane Garden Supplies, an invented garden supplies shop, finds eleven scripts in its templates. It retires four: an analytics snippet from the previous generation of Google Analytics, a heatmap tool whose trial ended two years earlier, an affiliate pixel for a programme the shop left, and a second copy of the Meta pixel's base code in the footer. It moves seven: the consent platform's script, the GA4 tag and purchase event, the Google Ads conversion tag, the Meta pixel and its purchase event, the active affiliate pixel, a review platform's post-purchase script and the chat widget. All seven are rebuilt in three workspaces and compared in preview; the consent platform moves to its gallery template on the consent initialisation trigger, and the Google tag moves with it, so nothing needs to stay in code.
The release flag goes into the templates on a Tuesday. Daily purchases across the cut-over:
| Day | Orders in the shop | GA4 purchases | Meta purchases |
|---|---|---|---|
| Monday (before) | 141 | 134 | 129 |
| Tuesday (release) | 138 | 132 | 251 |
| Wednesday | 145 | 139 | 266 |
| Thursday | 139 | 133 | 254 |
| Friday (fix) | 143 | 136 | 131 |
GA4 holds steady. Meta purchases nearly double from Tuesday. The confirmation page took its context push, and so the release flag, from the shared header the release updated, but the old Meta purchase script lived in a snippet file of the separate checkout theme, which the release did not touch. The flag let the new tag fire and could do nothing about old code the release had missed. A search of every theme file finds the script on Thursday; Friday's checkout theme release removes it, and Meta returns to its usual level. The shop adds the checkout theme's files to the inventory and to the publish checklist.
After the move
The migration ends; the container's life begins. Three things decide whether it stays better than the templates it replaced.
Governance from the first day. Naming, one change per workspace, a second reviewer, separate edit and publish rights and version notes are what the governance guide sets out, and the tag governance guide puts them in the wider stack's terms. A container adopted without them becomes the container engineering feared.
New tags through the container only. Requests for new tags now go to the container, with a data layer change where needed, never into the templates. CMS plugins and platform integrations that add scripts of their own are the usual way hard-coded tags return; check the page source at each audit against the exceptions list.
Deduplication watched, not assumed. Platforms that also receive server-side events need the same event identifier on the container tag as on the server send, or the move swaps one kind of double count for another; DeduplicationRemoving double counts when one conversion is reported by more than one source. is checked in each platform's own tools. And consentA Google tag feature that adjusts what tags collect according to the visitor's consent choices. settings on every moved tag are part of each audit, because a tag copied without its consent requirement is a privacy regression no report will show. Affiliate conversion tags are the move most likely to be noticed by someone outside the business, because partners see the gap in their own reports; the tutorial on tracing missing affiliate conversions works such a report back to the tag or trigger that broke.
When the tags move as part of a new platform or domain rather than into a container on the same site, the tutorial on moving a website without breaking Meta Ads covers what else in a Meta account depends on the site, from URL-rule audiences to catalog identifiers.
Common mistakes
- Moving without an inventory. The tags nobody listed are the ones that keep running in the templates and double every count.
- Copying selectors into the container. Scraped values break at the next redesign; the data layer contract is the point of the move.
- Removing old code before the container tags are live. The gap shows in reports and, worse, in ad platforms' bidding.
- Running old and new against the same destination to compare. The comparison costs a week of doubled conversions.
- Forgetting separate templates. Checkout themes, landing page builders and help centres often sit outside the main release.
- Moving the consent default into the container while the Google tag stays in code. The default arrives after the tag that needed it.
- Comparing new counts with the old tags only. The old tags may have been wrong; compare with the system of record.
- No exceptions list. The tags that stayed in code get added to the container a year later by someone who did not know.
The Tag Manager hub lists the other guides in this section, including the debugging tutorial that every step of the migration leans on.
