---
name: gas-deploy
description: Deploy a Google Apps Script web app with clasp — deployment-ID hygiene, /exec versus /dev, archiving stale deployments, and the auth traps. Use when the user says "deploy", "push to Apps Script", "clasp deploy", or names a gas-webapp project.
allowed-tools:
  - Bash
  - Read
  - Grep
---

# gas-deploy

Apps Script deployment is a recurring source of lost time, almost always for
one of four reasons below rather than anything to do with the code.

Read the repo's `docs/deploy-runbook.md` first — it holds this project's
deployment IDs, script ID, and any project-specific steps. This skill is the
procedure and the traps; the runbook is the specifics. Where they disagree, the
runbook wins.

## Never deploy unasked

`~/.claude/CLAUDE.md` and every scaffolded `CLAUDE.md` say it: run verify before
every push, never deploy without being asked. Deployment is outward-facing.
Confirm before the first `clasp deploy` of a session, every session.

## 1. Pre-flight

```
clasp --version
clasp push --watch=false
```

If `clasp` is not on `PATH`, stop and report the install command. Never
`npm install -g` on the user's behalf.

Confirm `.clasp.json` exists and is gitignored, and that `.clasp.json.example`
is committed with the script ID redacted (repo-standards §2.1 layer 3). A real
script ID in a tracked file is the same class of mistake as a committed key.

## 2. The four traps, in the order they bite

1. **`/exec` versus `/dev`.** `/dev` serves the current saved code to the
   owner and nobody else. `/exec` serves a *specific numbered deployment* to
   everyone. Testing on `/dev` and announcing on `/exec` is the single most
   common false "it works". Always verify on the `/exec` URL you are about to
   hand over.
2. **Deployment-ID drift.** `clasp deploy` without `-i` creates a *new*
   deployment with a *new* ID and a new `/exec` URL. Every previously shared
   link keeps serving the old code. Redeploy the existing ID:

   ```
   clasp deployments
   clasp deploy -i <deployment-id> -d "<what changed>"
   ```

   Record the ID in `docs/deploy-runbook.md` and never create a second
   long-lived one.
3. **Stale deployments accumulate.** Apps Script caps deployments per project.
   Archive with `clasp undeploy <id>` — but read `clasp deployments` first and
   confirm the ID is not the live one. Undeploying the live deployment takes
   the app down, and it is not undoable from the CLI.
4. **Auth and caching.** A logged-in Google account that is not the script
   owner sees a stale or permission-denied page that looks like a deploy
   failure. Verify in an incognito window, signed in as the intended audience.
   `clasp login --status` confirms which account clasp itself is using; it is
   frequently not the one in the browser.

## 3. Verify

Open the `/exec` URL in incognito. Confirm the change is visible and the
version string, if the app has one, matches what was just deployed. Do not
report success from a `clasp deploy` exit code alone — it reports that the
deployment was created, not that the app works.

## 4. Record

Append to `CHANGELOG.md` under Unreleased if the deployment carries a
user-visible change, and update `docs/deploy-runbook.md` if any ID changed.