Automated deployment and management of unified analytics tracking across all your GitHub repositories.

This platform:

• Discovers and classifies your GitHub repositories
• Sets up Google Analytics 4 (GA4) + Google Tag Manager (GTM) for unified tracking
• Injects tracking snippets into eligible repos
• Deploys a secure Cloudflare Worker proxy for API access
• Builds a central GitHub Pages dashboard with analytics visualizations

• Node.js: v18 or later
• npm: v9 or later
• Git: Latest version
• GitHub CLI: gh (optional but recommended)
• Cloudflare Wrangler: For Worker deployment

# Install dependencies
npm install

# Install Playwright browsers (for validation)
npx playwright install

1. Copy the example config:

   cp config/brand.config.example.json config/brand.config.json

2. Edit config/brand.config.json with your settings (see Configuration below)

# Authenticate with GitHub
gh auth login --scopes repo,read:user,user:email

# Token will be auto-retrieved, or set manually:
export GITHUB_TOKEN="your_token"

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable APIs:
   • Google Analytics Admin API
   • Google Tag Manager API
4. Create OAuth credentials (Web application)
5. Add redirect URI: http://localhost:8080/oauth2callback
6. Download credentials JSON as google-oauth-credentials.json in repo root
7. Authorize locally:

   npm run auth:ga4

8. Set GA4 property ID:

   export GA4_PROPERTY_ID="525629873"

# Install wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Set API token
export CLOUDFLARE_API_TOKEN="your_token"

# See what would happen without making changes
npm run apply -- --dry-run

# Execute the automation
npm run apply

# Run validation tests
npm run validate

Define events, variables, triggers, and tags as code, then let the agent apply them:

# 1) create strategy file from template
cp config/analytics.strategy.example.json config/analytics.strategy.json

# 2) preview changes (no writes)
npm run strategy:plan

# 3) apply to GA4 + GTM
npm run strategy:apply

Notes:

• npm run auth:ga4 now requests GA4 + GTM write scopes.
• Re-run auth after scope changes to refresh consent.

# Use a different config file
npm run apply -- --config config/brand.prod.json

# Filter repos
npm run apply -- --include-filter "my-project-*"
npm run apply -- --exclude-filter "temp-*"

Repos are classified into three buckets:

After npm run apply completes, you'll see:

TOTAL_REPOS_SCANNED=50
TOTAL_ELIGIBLE_REPOS=25
EXCLUDED_PASSIVE_CLONES=20
ALREADY_IMPLEMENTED=10
NET_NEW_IMPLEMENTED=15
DRIFT_REPAIRED=2
FAILED=0
DASHBOARD_VALIDATION=PASS
REPORT_JSON_PATH=reports/latest.json

The state/state.json file tracks:

• Repository classifications
• Implementation status
• Last applied/validation timestamps
• Errors (if any)

This enables idempotent re-runs months later.

Error: API rate limit exceeded

Solution: Use authenticated token (not anonymous). Consider GITHUB_TOKEN from GitHub App for higher limits.

Error: User does not have sufficient permissions

Solution: Verify OAuth scopes and that the signed-in OAuth user has access to the GA4 property/GTM container.

Error: Worker script not found

Solution: Ensure scripts/proxy-worker.js exists and wrangler.toml is configured correctly.

Error: Push rejected

Solution: Check that you have write access to the dashboard repo and the Pages branch.

# Enable verbose logging
export DEBUG=brand-analytics:*
npm run apply

To reset state for a specific repo:

# Edit state.json and remove the repo entry
# Or delete state.json entirely to start fresh
rm state/state.json

• Never commit tokens or credentials to the repository
• Use .env file (included in .gitignore) for local development
• Cloudflare Worker secrets store GA4 credentials securely
• GitHub Pages dashboard reads only aggregated data (no raw analytics exposed)

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  GitHub Repos   │────▶│   GTM Container │────▶│   GA4 Property  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Dashboard UI   │◀────│ Cloudflare Worker│◀────│  GA4 Data API   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

MIT