GitHub PR Sheets - Apps Script Integration

View and manage GitHub pull requests directly from Google Sheets using octo-sts for secure workload identity authentication.

Features

• Two-way sync: View PR data and push updates back to GitHub
• Editable fields: State (open/closed), Title, Labels, Assignees, Auto-merge
• Change tracking: Visual highlighting of pending changes
• Smart validation: Dropdowns for state and auto-merge fields
• Auto-refresh: Loads PRs automatically when you open the sheet
• Keyless auth: No personal access tokens needed

Setup

1. Install octo-sts GitHub App

Install the octo-sts GitHub App on your repository.

2. Create Google Apps Script

1. Open a Google Sheet
2. Go to Extensions > Apps Script
3. Copy the contents of Code.js into the script editor
4. Copy the contents of appsscript.json into the manifest (enable "Show appsscript.json" in settings)
5. Save the project

3. Configure the Integration

1. In your spreadsheet, open GitHub PRs > Configure...
2. Enter your GitHub repository owner and name
3. Optionally customize the identity name and sheet name
4. Click Save Configuration

4. Get Token Info

1. Go to GitHub PRs > Show OIDC Token Info
2. Copy the sub (subject) and aud (audience) values

5. Create Trust Policy

Create .github/chainguard/<identity-name>.sts.yaml in your repository:

# Trust policy for Apps Script workload identity
issuer: https://accounts.google.com

# Subject: Your email or Apps Script user ID
subject: "your-email@example.com"

# Audience: Apps Script client ID (from token info)
audience: "123456789-abcdefghijklmnop.apps.googleusercontent.com"

permissions:
  pull_requests: write
  issues: write

Note: The audience field is supported in octo-sts as of PR #508.

6. Load Pull Requests

Go to GitHub PRs > Refresh Pull Requests

Usage

Viewing PRs

The sheet displays:

• PR Number (read-only)
• Title (editable)
• State (editable dropdown: open/closed)
• Created/Updated dates (read-only)
• Labels (editable, comma-separated)
• Assignees (editable, comma-separated)
• Auto-merge (editable dropdown: enabled/disabled)

Making Changes

1. Edit any editable field
2. Changed cells are highlighted in dark yellow (#ffc107)
3. Rows with changes are highlighted in light yellow (#fff3cd)
4. View all pending changes: GitHub PRs > Show Pending Changes
5. Apply changes: GitHub PRs > Apply Changes to GitHub

Change Tracking

• Changes are tracked against original values from last refresh
• If you change a value and then change it back to the original, the highlight is removed
• Multiple fields can be changed per row before pushing
• Original values are stored in a hidden sheet

Development

Using clasp

# Install clasp
npm install -g @google/clasp

# Login
clasp login

# Clone your project
clasp clone <script-id>

# Push changes
clasp push

How It Works

1. OIDC Token: Uses ScriptApp.getIdentityToken() to generate a Google OIDC token
2. Token Exchange: Exchanges the OIDC token with octo-sts for a GitHub token
3. GitHub API: Uses the GitHub token to read and update pull requests
4. Trust Policy: octo-sts validates the token's issuer, subject, and audience against your trust policy

Troubleshooting

"Invalid token" error

• Verify your trust policy's subject and audience match the values from Show OIDC Token Info
• Ensure octo-sts app is installed on your repository
• Check that the identity name matches your .sts.yaml filename

Changes not applying

• Make sure you've granted pull_requests: write permission in the trust policy
• Check that the PR is still open (can't edit closed PRs)
• Review Apps Script logs for detailed error messages

Auto-merge not working

• Requires pull_requests: write permission
• PR must meet all branch protection requirements
• Check if auto-merge is allowed in your repository settings