Home › Google Apps Script › Google Apps Script Copilot instructions

Google Apps Script Copilot instructions

Copilot instructions for Google Apps Script projects with clasp: V8 runtime, batch Sheets operations, quotas and the 6-minute limit, PropertiesService secrets, and triggers.

GitHub CopilotGoogle Apps Script

Copy copilot-instructions.md

How to use

Save this as .github/copilot-instructions.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# Copilot instructions — Google Apps Script

## Workflow
- Code is synced with clasp: `clasp push` uploads local files, `clasp pull` downloads. `.clasp.json` holds the script ID; `appsscript.json` holds the manifest. Don't run `clasp push` or `clasp deploy` unless asked.
- TypeScript (if used) compiles locally before push; keep the `@types/google-apps-script` package current.

## Runtime rules
- V8 runtime (`"runtimeVersion": "V8"`): modern JS is fine, but there are no Node modules, `require`, `fetch` or DOM. Use `UrlFetchApp`, `Utilities`, and the Google services.
- Batch everything: read a range once with `getValues()`, transform in memory, write once with `setValues()`. Never call `getValue()`/`setValue()` inside loops.
- Executions stop at about 6 minutes (shorter for custom functions). For long jobs, process in chunks, save progress in `PropertiesService`, and schedule a continuation with a time-based trigger.
- Use `CacheService` for repeated lookups and `LockService` around code that can run concurrently (form submits, triggers).
- Custom functions (`=MYFUNC()`) must be fast and pure: no services that need authorization, no side effects.

## Security and scopes
- Secrets and config in `PropertiesService.getScriptProperties()`, never in source.
- Declare the narrowest `oauthScopes` in `appsscript.json` (e.g. `spreadsheets.currentonly` instead of full Drive) and list any added scope in the PR.
- `UrlFetchApp.fetch(url, { muteHttpExceptions: true })` and check `getResponseCode()`; never log tokens or full responses with personal data.
- Web apps: set `executeAs` and `access` deliberately; validate every `doGet`/`doPost` parameter.

## Triggers and UI
- Installable triggers are created by a setup function that first deletes duplicates; document them in the README.
- Menus via `onOpen(e)` with `SpreadsheetApp.getUi().createMenu(...)`; long actions show a toast or sidebar progress instead of freezing.
- Wrap entry points in try/catch and log with `console.error` (Cloud Logging) including the function name.