🏷️ NinjaDataBuilder™ Google Tag Manager for n8n

Role-separated, bounded Google Tag Manager API v2 nodes and OAuth credentials for self-hosted n8n.

[!IMPORTANT]
The current release is @ninjadatabuilder/n8n-nodes-google-tag-manager@0.5.6, updated and validated for the recent self-hosted n8n 2.36.7 release. The previously stable validated package 0.5.5 remains mapped to n8n 2.35.3; the earlier stable package 0.5.3 remains mapped to n8n 2.32.5. Pin the version in production and validate the package in staging first.

[!WARNING]
This is an unverified community node. It is intended for self-hosted n8n; unverified community nodes are not available on n8n Cloud.

🧭 Start here

🎯 What this package does

The package exposes named, allow-listed n8n nodes for bounded GTM operations. It uses separate OAuth credentials and scope boundaries for four operational roles:

It does not expose an arbitrary HTTP method/path/payload dispatcher.

🎬 Demonstration

The screenshots below show a practical self-hosted n8n setup using the role-separated GTM nodes and credentials.

Creating a GTM container

A manual workflow starts the one-time GTM Admin creation process, loads the centralized Configuration step, and creates a Sites RJ GTM container.

Role-separated GTM credentials

The n8n credentials screen shows separate Google Tag Manager OAuth credentials for Admin, Publisher, Read Only, and Editor operations.

Workflow video

The 73-second demonstration shows a safe Editor workflow that reads existing variables, confirms the creation path, and creates a temporary GTM constant variable using values from the Configuration node.

[!NOTE]
These screenshots, the inline video, and the full video are demonstrations of the workflow and credential structure. Do not publish credentials, tokens, account identifiers, or production data in screenshots, recordings, or issue attachments.

🚀 Five-minute safe start

1. Use a self-hosted n8n instance with Community Nodes enabled.

2. Install the pinned package from Settings → Community Nodes → Install:

   @ninjadatabuilder/n8n-nodes-google-tag-manager@0.5.6
   

3. Create the Read credential in the n8n credential screen.

4. Build a manual workflow with one account, container, or status read.

5. Confirm that OAuth works and the Google account can access the intended GTM resources.

6. Keep Editor, Publisher, and Admin workflows manual and inactive until their targets and payloads are reviewed.

[!NOTE]
GUI installation requires Owner or Admin permission in n8n. The package itself does not need to be cloned for end-user installation.

✅ Requirements

• self-hosted n8n;
• Owner or Admin permission to install community nodes;
• registry.npmjs.org network access;
• Google Cloud access to configure OAuth;
• a Google account with access to the target GTM account/container;
• staging, backup, and rollback before production installation.

🔐 Secrets and OAuth

Enter Client ID, Client Secret, refresh tokens, access tokens, and passwords only in n8n's encrypted credential store.

Google Cloud OAuth client
        │
        ▼
n8n credential screen
        │
        ▼
role-specific GTM node

The package does not accept tokens through workflow fields or operation parameters. A successful OAuth grant also does not guarantee that the Google user has access to the requested GTM account or container.

🧩 Role and permission matrix

Use the smallest role that can complete the task. Do not reuse Admin for ordinary reads or Publisher for Editor work.

🐳 Environment-managed installation

Use this path when n8n services are managed from Docker or deployment configuration:

N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
N8N_COMMUNITY_PACKAGES_ENABLED=true
N8N_UNVERIFIED_PACKAGES_ENABLED=true
N8N_COMMUNITY_PACKAGES_REGISTRY=https://registry.npmjs.org
N8N_COMMUNITY_PACKAGES=[{"name":"@ninjadatabuilder/n8n-nodes-google-tag-manager","version":"0.5.6"}]

Restart the editor, worker, webhook, and runners according to your architecture.

[!CAUTION]
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true makes the declared list authoritative. Packages installed through the UI but omitted from the list may be removed at startup. Inventory and preserve the existing package list before enabling this mode.

For stronger supply-chain control, pin the version and use the npm tarball SHA-512 checksum where your deployment process supports it.

✍️ Publisher workflow

Use this order:

read state → review workspace → preview → create explicit version → review version → publish explicitly

[!WARNING]
Create Version is not a preview. It creates a real GTM version, consumes the source workspace, and returns a replacement workspace. Review fingerprints, IDs, names, and impact before confirming.

[!CAUTION]
Publication requires both Confirm Publish = true and the literal text PUBLICAR {versionId}. For example: PUBLICAR 123456. PUBLISH 123456 is rejected.

Do not schedule publication and do not expose Publisher or Admin as a generic AI tool.

🚫 What this package does not do

• It does not support unverified installation on n8n Cloud.
• It does not manage GTM users or permissions.
• It does not delete containers.
• It does not publish automatically or on a schedule.
• It does not convert an OAuth scope into GTM access the user does not have.
• It does not replace staging, backup, review, or rollback.
• It does not accept arbitrary API endpoints, methods, paths, or payloads.

🔄 Upgrade, rollback, and uninstall

Controlled upgrade

1. Back up the n8n instance.
2. Install the new package version in staging.
3. Run the Read smoke test.
4. Compare behavior and logs.
5. Update production only after validation.

UI rollback

1. Open Settings → Community Nodes.
2. Select Options → Uninstall package.
3. Reinstall the previous pinned version.
4. Restart n8n if requested.
5. Run the Read smoke test again.

Environment rollback

Restore the previous N8N_COMMUNITY_PACKAGES entry and restart only the affected n8n services. Do not remove PostgreSQL, Redis, or n8n volumes to solve a package problem.

🧪 Troubleshooting

📚 Documentation

• Português do Brasil — guia completo
• English — complete guide
• Installation reference — Português
• Installation reference — English
• Permission contract
• Architecture
• Security reporting
• Google Tag Manager API v2
• n8n community node installation

🛠️ Development checks

npm ci
npm test
npm audit --omit=dev
npm pack --dry-run
git diff --check

Do not commit OAuth values, account/container IDs, customer identifiers, workflow exports, execution data, or production payloads.

📄 License

MIT. See LICENSE.