# apps-script-github-sync

> Set up and manage synchronization between GitHub repositories and Google Apps Script projects using clasp and GitHub Actions. Use when: (1) Creating a new Apps Script project with GitHub version control, (2) Setting up CI/CD for existing Apps Script projects, (3) Configuring stable deployment URLs that persist across updates, (4) Troubleshooting clasp authentication or deployment issues, (5) Managing Apps Script deployments from the command line.

- Author: robhester-ant
- Repository: robhester-ant/rob-claude-skills
- Version: 20251220141224
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/robhester-ant/rob-claude-skills
- Web: https://mule.run/skillshub/@@robhester-ant/rob-claude-skills~apps-script-github-sync:20251220141224

---

---
name: apps-script-github-sync
description: "Set up and manage synchronization between GitHub repositories and Google Apps Script projects using clasp and GitHub Actions. Use when: (1) Creating a new Apps Script project with GitHub version control, (2) Setting up CI/CD for existing Apps Script projects, (3) Configuring stable deployment URLs that persist across updates, (4) Troubleshooting clasp authentication or deployment issues, (5) Managing Apps Script deployments from the command line."
---

# Google Apps Script + GitHub Sync

Synchronize Google Apps Script projects with GitHub repositories using clasp (Google's CLI tool) and GitHub Actions for automatic deployment.

## Prerequisites

- **Node.js** (v18+) and npm
- **jq** - JSON processor (used by setup scripts): `brew install jq` or `apt install jq`
- **clasp** - Google's CLI for Apps Script: `npm install -g @google/clasp`

## Required Configuration

Prompt the user for these values before proceeding:

| Placeholder | Description | How to Obtain |
|-------------|-------------|---------------|
| `SCRIPT_ID` | Apps Script project ID | Project Settings in script.google.com, or create via `clasp create` |
| `GITHUB_REPO` | Repository (owner/repo) | User provides |
| `DEPLOYMENT_ID` | Stable deployment ID | Created via `clasp deploy`, then reused |
| `PROJECT_NAME` | Human-readable name | User provides |

## Workflow Decision Tree

### New Project Setup
1. Initialize clasp → Create Apps Script project → Link to GitHub → Configure Actions

### Existing Project
1. Clone with clasp → Set up GitHub repo → Configure Actions

### Update Deployment (Stable URL)
1. `clasp push` → `clasp deploy -i DEPLOYMENT_ID`

### Troubleshoot Auth
See [references/troubleshooting.md](references/troubleshooting.md)

## Initial Setup Workflow

### Step 1: Install and Authenticate clasp

```bash
npm install -g @google/clasp
clasp login
```

Verify Apps Script API is enabled: https://script.google.com/home/usersettings

### Step 2: Initialize Project

**New project:**
```bash
cd /path/to/repo
clasp create --title "PROJECT_NAME" --type standalone
```

**Existing Apps Script:**
```bash
cd /path/to/repo
clasp clone SCRIPT_ID
```

### Step 3: Configure Project Structure

Create `.clasp.json`:
```json
{
  "scriptId": "SCRIPT_ID",
  "rootDir": "./src"
}
```

Create `src/appsscript.json`:
```json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": []
}
```

Create `.claspignore`:
```
**/**
!src/**
.git/**
node_modules/**
```

Add to `.gitignore`:
```
.clasprc.json
node_modules/
```

### Step 4: Create Initial Deployment (Stable URL)

```bash
clasp push
clasp deploy --description "Initial deployment"
```

**Save the deployment ID** from output (starts with `AKfycb...`). This is `DEPLOYMENT_ID`.

The stable web app URL will be:
```
https://script.google.com/macros/s/DEPLOYMENT_ID/exec
```

### Step 5: Configure GitHub Actions

Extract clasp credentials for CI/CD:
```bash
cat ~/.clasprc.json
```

Add as GitHub secret `CLASPRC_JSON` at: `https://github.com/GITHUB_REPO/settings/secrets/actions`

Create `.github/workflows/deploy-apps-script.yml`:
```yaml
name: Deploy to Google Apps Script

on:
  push:
    branches: [main]
    paths: ['src/**', 'appsscript.json', '.clasp.json']
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install clasp
        run: npm install -g @google/clasp
      
      - name: Authenticate
        run: echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json
      
      - name: Push and deploy
        run: |
          clasp push --force
          clasp deploy -i DEPLOYMENT_ID --description "Deploy ${{ github.sha }}"
```

**Critical:** Replace `DEPLOYMENT_ID` in the workflow file with the actual ID.

## Local Development Commands

| Command | Purpose |
|---------|---------|
| `clasp push` | Upload local → Apps Script |
| `clasp push --force` | Overwrite remote |
| `clasp pull` | Download Apps Script → local |
| `clasp open` | Open in browser editor |
| `clasp logs --watch` | Stream execution logs |
| `clasp deploy -i ID` | Update existing deployment |
| `clasp deployments` | List all deployments |

## OAuth Scopes Reference

Add required scopes to `appsscript.json`:

```json
{
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}
```

Only include scopes the script actually uses.

## Project Structure

```
repo/
├── .clasp.json           # Script ID and config
├── .claspignore          # Files to exclude
├── .github/workflows/
│   └── deploy-apps-script.yml
├── src/
│   ├── appsscript.json   # Manifest with scopes
│   ├── Code.js           # Main entry point
│   └── *.js              # Additional modules
└── .gitignore            # Exclude .clasprc.json
```

## Troubleshooting

For common issues (auth failures, push errors, deployment problems), see [references/troubleshooting.md](references/troubleshooting.md).

## Bundled Resources

### Scripts

| Script | Purpose |
|--------|---------|
| `scripts/init_apps_script.sh` | Initialize new project with full setup |
| `scripts/extract_credentials.sh` | Extract and validate clasp credentials for GitHub |

### References

| File | When to Use |
|------|-------------|
| [references/troubleshooting.md](references/troubleshooting.md) | Auth failures, push errors, deployment issues |
| [references/github-actions.md](references/github-actions.md) | Advanced workflow configs (multi-env, releases, testing) |
| [references/apps-script-patterns.md](references/apps-script-patterns.md) | Common Apps Script code patterns |

## Security Notes

1. **Never commit `.clasprc.json`** — contains OAuth tokens
2. **Rotate credentials periodically** — re-run `clasp login`, update GitHub secret
3. **Use least-privilege scopes** — only request what the script needs
4. **For teams** — consider service accounts instead of personal OAuth