| name | chrome-webstore-release-blueprint |
| description | Guide a user end-to-end through setting up Chrome Web Store API release automation in any repository. Use when asked to walk someone through OAuth/CWS credential setup, refresh token creation, local/CI secret setup, version-based publish automation, and submission status checks. |
Chrome Web Store Release Blueprint
Use this skill as a hands-on setup guide. The agent should lead the user step-by-step, ask for confirmations, and only automate the parts that can be done locally/in CI.
What This Skill Is For
- Helping a user set up Chrome Web Store release automation from scratch.
- Giving clear manual instructions for Google/CWS dashboard steps.
- Implementing repo-side scripts/workflows after the user provides credentials.
- Verifying submission state (
PUBLISHED, PENDING_REVIEW, etc.).
Agent Behavior Rules
- Treat dashboard/OAuth tasks as user-driven; do not imply you performed them.
- Give one clear step at a time and wait for confirmation before moving on.
- Ask for exact values only when needed, and tell user where each value comes from.
- Mask secrets in logs and never commit secret values to git.
- If
gh is available, offer secret upload automation; if not, provide manual fallback.
Step 1: Project Discovery (Before Any Credential Work)
Collect these inputs:
- manifest path containing extension version
- build command
- zip/package command and output file name/path
- CI platform (GitHub Actions by default)
- release branch policy (
main, tags, or manual dispatch)
- local secret file convention (
.env, .env.local, etc.)
Ask explicitly:
- "Do you want CI to publish only when version changes?"
- "Do you want me to wire GitHub secret upload via
gh?"
Step 2: Detailed Credential Walkthrough (User + Agent)
2.1 Enable API in Google Cloud
Tell user to open:
https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com
User actions:
- Select the intended Google Cloud project.
- Click
Enable for Chrome Web Store API.
Agent prompt example:
- "When Chrome Web Store API shows as Enabled, tell me and I will move to OAuth setup."
2.2 Configure OAuth Consent Screen
Tell user to open one of:
https://console.cloud.google.com/apis/credentials/consent
- If UI redirects, continue in Google Auth Platform consent screen pages.
User actions:
- Choose
External user type (for non-Workspace internal apps).
- Fill app name, support email, developer contact email.
- Save and continue through scopes unless custom scopes are required.
- Add your own Google account as a test user if app is in Testing mode.
- Save.
Agent guidance:
- If user wants stable long-lived refresh token behavior, recommend moving consent screen to Production when ready.
2.3 Create OAuth Client
Tell user to open:
https://console.cloud.google.com/apis/credentials
User actions:
- Click
Create Credentials -> OAuth client ID.
- Choose application type
Web application.
- Add authorized redirect URI exactly:
https://developers.google.com/oauthplayground
- Create client.
Capture values:
CWS_CLIENT_ID
CWS_CLIENT_SECRET
Agent prompt example:
- "Paste
CWS_CLIENT_ID and CWS_CLIENT_SECRET when ready (I will treat them as secrets)."
2.4 Generate Refresh Token (OAuth Playground)
Tell user to open:
https://developers.google.com/oauthplayground/
User actions:
- Click the settings gear icon.
- Enable
Use your own OAuth credentials.
- Paste
CWS_CLIENT_ID and CWS_CLIENT_SECRET.
- In Step 1, enter scope:
https://www.googleapis.com/auth/chromewebstore
- Click
Authorize APIs.
- Sign in with the same Google account that owns/publishes the extension.
- Click
Exchange authorization code for tokens.
- Copy refresh token.
Capture value:
Agent prompt example:
- "Paste
CWS_REFRESH_TOKEN now. I will only place it in local secret storage/CI secrets."
2.5 Capture Store IDs
Capture:
CWS_EXTENSION_ID (the extension item ID from store/developer listing URL)
CWS_PUBLISHER_ID (developer/publisher ID from Chrome Web Store developer account context)
Agent instruction:
- If user is unsure, ask them to open the Chrome Web Store Developer Dashboard and copy IDs from item/account URLs or account details.
2.6 Credential Checklist
Do not proceed until all five exist:
CWS_CLIENT_ID
CWS_CLIENT_SECRET
CWS_REFRESH_TOKEN
CWS_PUBLISHER_ID
CWS_EXTENSION_ID
Step 3: Local Secret File and CI Secret Setup
Create a local template file (no real values committed):
CWS_CLIENT_ID=
CWS_CLIENT_SECRET=
CWS_REFRESH_TOKEN=
CWS_PUBLISHER_ID=
CWS_EXTENSION_ID=
Ensure real secret file path is gitignored.
If using GitHub Actions, ask user if gh automation is desired.
If yes, verify:
gh --version
gh auth status
If gh auth is missing, tell user to run:
Then implement a helper script that:
- reads secret values from local env file
- validates all required keys are present
- supports
--dry-run
- masks values in dry-run output
- uploads with
gh secret set ... --repo ...
- fails fast on missing keys/auth
If user declines gh, provide manual secret entry checklist for repository settings.
Step 4: Release Workflow Blueprint (Version-Triggered)
Design the CI workflow around this logic:
- Read local manifest version.
- Optionally compare with a secondary version file and fail on mismatch.
- Exchange refresh token for access token:
POST https://oauth2.googleapis.com/token
- Fetch CWS status:
GET https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:fetchStatus
- Extract current published version from:
publishedItemRevisionStatus.distributionChannels[0].crxVersion
- If local version == published version, skip publish.
- If version changed:
- build package zip
- upload zip:
POST https://chromewebstore.googleapis.com/upload/v2/publishers/<publisherId>/items/<extensionId>:upload
- handle async upload state with polling when needed
- publish:
POST https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:publish
Treat these publish states as successful submission:
PENDING_REVIEW
PUBLISHED
PUBLISHED_TO_TESTERS
STAGED
Step 5: Submission Status Checker Blueprint
Create a script dedicated to "what is the latest submission state?".
Required behavior:
- accepts env values (and optional
--env-file)
- optionally accepts
--manifest for local version comparison
- supports
--json
- calls token endpoint +
fetchStatus
- outputs normalized fields:
itemId
localVersion
publishedVersion
publishedState
submittedVersion
submittedState
upToDate
pendingReview
- exits non-zero on auth/API/input errors
Helpful checks to include:
- flag version mismatch between manifest and package metadata
- show whether uploaded version is pending review but not yet published
- print concise human summary when
--json is not used
Step 6: Guided Verification Flow
Run this with the user:
- Confirm status checker runs successfully before release.
- Bump extension version (patch) in all version sources.
- Push branch and trigger workflow.
- Confirm workflow either:
- skips (if no version change), or
- uploads and submits publish.
- Re-run status checker:
- expect
PENDING_REVIEW first in many cases
- later expect published channel to match local version
Troubleshooting Script (What Agent Should Say)
invalid_grant:
- likely wrong/expired refresh token, wrong OAuth client, or wrong account
403 from CWS endpoint:
- account lacks publisher permissions for that extension
- workflow no-op:
- local version equals published version by design
- upload failure:
- inspect API response and packaged zip structure/manifest validity
- version mismatch guard failure:
- align all declared version files before publishing
Practical Links (Share During Guidance)
- Chrome Web Store API overview:
https://developer.chrome.com/docs/webstore/using-api
- Publish endpoint:
https://developer.chrome.com/docs/webstore/publish
- OAuth Playground:
https://developers.google.com/oauthplayground/
- API enablement page:
https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com
- Credentials page:
https://console.cloud.google.com/apis/credentials
Guardrails
- Never commit credentials.
- Never hardcode secrets in workflow YAML.
- Never auto-publish every push without version comparison.
- Keep setup instructions explicit and user-confirmed at each manual step.
- Prefer repeatable helper scripts over ad-hoc one-off commands.