03 — Deployment & Management

This document defines how to deploy the Adventive Looker Studio connector, manage versioning, publish to the marketplace, and roll back. The connector runs entirely as a Google Apps Script project — there is no server infrastructure to manage.

Prerequisites

Tools

Node.js (v18+) and npm — required to install clasp
clasp — Google’s command-line tool for Apps Script projects
Google account — must be a project owner or editor on the Apps Script project

Install `clasp`

npm install -g @google/clasp
clasp login

clasp login opens a browser OAuth flow. Use the Google account that owns the Apps Script project. Credentials are stored in ~/.clasprc.json.

Clone credentials

After first login, authenticate against the Apps Script project:

cd /path/to/google-data-studio-connector.git
clasp clone <SCRIPT_ID>

The SCRIPT_ID is found in the Apps Script editor: Project Settings → Script ID. This creates a .clasp.json file in the repository root. Do not commit .clasp.json — it is in .gitignore.

Environments

The connector has one production Apps Script deployment. There is no built-in environment promotion (unlike Cloudflare Workers). The recommended pattern is to maintain two separate Apps Script projects:

Environment	Purpose	Who uses it
`staging`	Verify changes before publishing	Engineering only
`production`	Live marketplace deployment	All paying customers

Each environment has its own SCRIPT_ID. Store them in a local .env or use separate .clasp.json files:

# Switch to staging
cp .clasp.staging.json .clasp.json && clasp push

# Switch to production
cp .clasp.production.json .clasp.json && clasp push

Never push directly to production without staging verification first.

Deploy flow

Standard deploy

1. Make changes in the repository
2. Push to staging
   clasp push   (with .clasp.json pointing to staging script ID)

3. Verify in staging (see Verification below)

4. Create a new deployment version in staging:
   clasp deploy --description "v<version> — <summary>"

5. Push to production
   cp .clasp.production.json .clasp.json
   clasp push

6. Create a new deployment version in production:
   clasp deploy --description "v<version> — <summary>"

7. Update the marketplace listing if the description or name changed
   (See Marketplace publishing below)

Pushing changes

clasp push

This uploads all .gs and appscript.json files from the local repository to the linked Apps Script project. It does not create a new versioned deployment — users on the connector continue to use the last published version until step 6.

Creating a versioned deployment

clasp deploy --description "v1.1.0 — Fix JSON parse bug, update to Looker Studio branding"

This creates a numbered version in Apps Script (v1, v2, v3…). Each version can be independently deployed via the Looker Studio marketplace. Keep a mapping of version numbers to semantic versions in CHANGELOG.md.

Viewing existing deployments

clasp deployments

Output example:

- AKfycbw... @1 - Initial
- AKfycbx... @2 - v1.1.0 — Fix JSON parse bug

Verification after deploy

After pushing to staging and creating a new deployment, run through this checklist manually:

1. Open Looker Studio (lookerstudio.google.com)
2. Create a new report → Add data → Search for "Adventive Ads for Looker Studio"
3. Select the staging deployment if prompted
4. Enter a valid Integration Key + API Key
   - Expected: "Connected" confirmation, no error
5. Enter an invalid API Key
   - Expected: "Invalid credentials" error from Looker Studio
   - NOT expected: a generic error or spinner that never resolves
6. Configure a date range with known data (use a recent 7-day window)
   - Expected: data appears in the table
7. Add a second chart with different fields
   - Expected: data appears correctly, no empty columns
8. Refresh the report (force cache miss by using a different date range)
   - Expected: data loads within ~5 seconds; no error
9. Check Cloud Logging (console.cloud.google.com → Logging → Log Explorer)
   - Expected: log entries for date range, no credential values visible

Marketplace publishing

The connector is listed in the Looker Studio connector gallery. Updating the marketplace listing requires a separate step after deploying a new version.

Update a published connector

Go to Google Workspace Marketplace SDK in the Cloud Console for the Apps Script project.
Navigate to App Configuration → Looker Studio connectors.
Select the target deployment version from the dropdown.
Save. The updated version is now active for new connector configurations. Existing report users are not affected until they re-authorize or re-configure.

When to republish

Any change to appscript.json (name, description, OAuth scopes)
Any change to the authentication flow
Any change to getConfig() or getSchema() that affects the user-facing setup

Purely backend changes (data fetching, caching) do not require republishing — they take effect immediately after clasp push and clasp deploy.

Version management

Use semantic versioning (MAJOR.MINOR.PATCH) with a CHANGELOG.md at the repository root.

Increment	When
PATCH	Bug fixes, security fixes, comment updates
MINOR	New fields added to the schema, non-breaking behavior changes
MAJOR	Auth type change, schema field removals, breaking API changes

Tag each release in git:

git tag v1.1.0 -m "Fix JSON parse bug, Looker Studio branding, security fixes"
git push origin v1.1.0

Rollback

Apps Script does not have an instant rollback command equivalent to wrangler rollback. Rollback is a re-deploy of the previous version.

Rollback procedure

# 1. Find the last known-good commit
git log --oneline

# 2. Check out that commit to a temp branch
git checkout <commit_sha> -b rollback/v<version>

# 3. Push to the affected environment
clasp push

# 4. Create a new deployment version with a rollback note
clasp deploy --description "ROLLBACK to v<version>"

# 5. Verify using the checklist above

# 6. If rolling back production, immediately post to the platform channel
#    documenting what was reverted and why

Do not delete the broken deployment version — preserve it for post-mortem analysis.

Credential management

User credentials (Integration Key + API Key)

Stored in PropertiesService.getUserProperties() per user
Engineers cannot access or reset individual user credentials
Users can reset their own credentials by going to the connector configuration in their Looker Studio report and clicking “Edit connection”

Connector credentials (Apps Script project access)

Managed via clasp login / ~/.clasprc.json
Only project owners and editors can push code
Rotate access by removing the account from the Apps Script project and re-running clasp login with the new account

Deploy freezes

Do not deploy to production during:

Active Adventive platform incidents
End-of-quarter close (last 3 business days of the quarter)
Major client campaign launches (announced ≥ 24 hours in advance)

Freeze announcements go in the platform Slack channel. Break-glass deploys during a freeze require written approval from the Platform lead in the same channel before proceeding.

Next: 04 — Runbook