Add github action to google sheet tracking

.github/ISSUE_TEMPLATE/Helpdesk.yml

@@ -2,7 +2,6 @@ name: Helpdesk Request
 description: Support request for build/config/runtime/performance/science questions
 title: "[Helpdesk] "
 labels: ["helpdesk"]
-assignees: [gibbsp]
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Submit a Helpdesk ticket
+    url: https://github.com/JCSDA-internal/.github/issues/new?template=Helpdesk.yml
+    about: Support requests (build, runtime, performance, science) — opens in the centralized helpdesk repo
   - name: JCSDA
     url: https://jcsda.org/
     about: JCSDA web site

.github/helpdesk/SETUP.md

@@ -0,0 +1,211 @@
+# Helpdesk Sheet Sync — Setup & Test Guide
+
+## Overview
+
+This guide walks through setting up and testing the Google Sheets integration
+for the JCSDA helpdesk system. On each helpdesk issue event (open, edit, close,
+etc.) a GitHub Actions workflow syncs issue data to a shared Google Sheet.
+
+---
+
+## Step 1 — Google Cloud: create the service account (~15 min)
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a new project (e.g., `jcsda-helpdesk`) or select an existing one
+3. **Enable APIs**: Navigation menu → APIs & Services → Library
+   - Search and enable **Google Sheets API**
+   - Search and enable **Google Drive API**
+4. **Create service account**: IAM & Admin → Service Accounts → **+ Create Service Account**
+   - Name: `jcsda-helpdesk-sheets`
+   - Skip project role (click through) — permissions come from the Sheet itself
+   - Click **Done**
+5. Click the new service account → **Keys** tab → **Add Key → Create new key → JSON**
+   - Save the downloaded `.json` file somewhere temporarily (you will paste it into GitHub next)
+   - Note the service account **email address**
+     (e.g., `jcsda-helpdesk-sheets@your-project.iam.gserviceaccount.com`)
+
+---
+
+## Step 2 — Create the Google Sheet (~5 min)
+
+1. Go to [sheets.google.com](https://sheets.google.com) → create a **Blank** spreadsheet
+2. Name it `JCSDA Helpdesk Tracker`
+3. **Share it with the service account**: Share button → paste the service account
+   email → set to **Editor** → Send
+4. Copy the **Sheet ID** from the URL bar:
+   ```
+   https://docs.google.com/spreadsheets/d/THIS_LONG_STRING_IS_THE_ID/edit
+   ```
+
+---
+
+## Step 3 — Configure the Sheet ID and add the GitHub Secret
+
+**Sheet ID** — open `.github/workflows/helpdesk-sheet-sync.yml` and paste your
+Sheet ID into the `HELPDESK_SHEET_ID` variable at the top of the file:
+
+```yaml
+env:
+  HELPDESK_SHEET_ID: "YOUR_SHEET_ID_HERE"
+```
+
+**Secret** — go to `github.com/JCSDA-internal/.github/settings/secrets/actions`
+and add one secret:
+
+| Name | Value |
+|---|---|
+| `GOOGLE_SERVICE_ACCOUNT_JSON` | Paste the **entire contents** of the downloaded `.json` key file |
+
+---
+
+## Step 4 — Add a test entry to the org map
+
+In [org_assignee_map.json](org_assignee_map.json), add at least one real
+org/username pair so you can verify auto-assignment works. Leave the rest as
+placeholders for now.
+
+```json
+{
+  "NOAA/NWS/EMC": "real-github-username",
+  ...
+}
+```
+
+---
+
+## Step 5 — Open the PR
+
+Push the branch containing the following files and open a PR in `JCSDA-internal/.github`:
+
+```
+.github/workflows/helpdesk-sheet-sync.yml      ← new
+.github/workflows/helpdesk-triage-labels.yml   ← bug fix
+.github/scripts/helpdesk_sheet_sync.py         ← new
+.github/helpdesk/org_assignee_map.json         ← new
+.github/helpdesk/SETUP.md                      ← this file
+.github/ISSUE_TEMPLATE/config.yaml             ← updated
+```
+
+> **Note:** `issues` event workflows only run from the **default branch**.
+> The Actions tab will show the workflow files during PR review, but the
+> triggers will not fire until the PR is merged. This is expected behavior.
+
+---
+
+## Step 6 — Merge and create the `helpdesk` label
+
+After merging, confirm the `helpdesk` label exists in the repo (the issue
+template references it). Check `github.com/JCSDA-internal/.github/labels` —
+if it is not there, create it manually with any color.
+
+---
+
+## Step 7 — Open a test issue
+
+Go to `github.com/JCSDA-internal/.github/issues/new/choose` → select
+**Helpdesk Request** and fill in every required field. Use a **Requesting
+Organization** value that matches your test entry in `org_assignee_map.json`
+to verify auto-assignment.
+
+---
+
+## Step 8 — Verify
+
+**GitHub Actions** (`github.com/JCSDA-internal/.github/actions`):
+- `Helpdesk → Google Sheet sync` should show a completed run
+  - Log should contain: `Appended new row for issue #N in JCSDA-internal/.github`
+- `Helpdesk triage → labels` should also show a completed run
+
+**GitHub issue:**
+- The configured liaison should appear as assignee
+- Labels `helpdesk` and any `triage:*` labels should be applied
+
+**Google Sheet:**
+- Row 1 should be a frozen, locked section-header row (auto-created on first run),
+  with four merged, labelled bands: **Ticket Information** | **Requester Information** |
+  **Work Tracking** | **Maintainer Notes**
+- Row 2 should be a frozen, locked column-header row
+- Row 3 should have all issue fields populated
+- Column D (`url`) should display `#N` as a clickable hyperlink
+
+**Close the test issue** and re-check the sheet:
+- `status` → `Closed`
+- `closed_at` → timestamp
+- `time_to_close_days` → a decimal number
+
+---
+
+## Sheet columns reference
+
+Row 1 carries merged section banners (locked). Row 2 carries the column headers
+(locked). Data begins at row 3.
+
+### Ticket Information (A–E)
+
+| Col | Name | Source |
+|-----|------|--------|
+| A | `issue_number` | Issue number — composite key with B |
+| B | `repo` | `owner/repo` — composite key with A |
+| C | `title` | Issue title |
+| D | `url` | `=HYPERLINK()` formula — renders as clickable `#N` |
+| E | `labels` | Comma-separated label names |
+
+### Requester Information (F–L)
+
+| Col | Name | Source |
+|-----|------|--------|
+| F | `opened_by` | Issue author login |
+| G | `opened_at` | ISO timestamp |
+| H | `requesting_org` | Form field: *Requesting Organization* |
+| I | `category` | Form field: *Issue category* |
+| J | `impact` | Form field: *Impact / priority* |
+| K | `reproducibility` | Form field: *Reproducibility* |
+| L | `platform` | Form field: *Platform / system* |
+
+### Work Tracking (M–Q)
+
+| Col | Name | Source |
+|-----|------|--------|
+| M | `assignees` | Comma-separated assignee logins |
+| N | `status` | `Open` or `Closed` |
+| O | `closed_at` | ISO timestamp, blank if open |
+| P | `time_to_close_days` | Decimal days from open to close, blank if open |
+| Q | `story_points` | Estimate field from GitHub Projects v2 |
+
+### Maintainer Notes (R–U)
+
+| Col | Name | Source |
+|-----|------|--------|
+| R | `triage_category` | Checked items under *Triage Category / Maintainer Classification* |
+| S | `root_cause` | Checked items under *Root Cause* |
+| T | `resolution_description` | Form field: *Resolution Description* |
+| U | `notes` | **Manually maintained — never overwritten by automation** |
+
+---
+
+## Credential security notes
+
+- The service account has no GCP project roles — its only access is the single
+  Sheet it was shared on
+- The `drive.file` OAuth scope used by the script limits it to files the service
+  account created or was explicitly shared on; it cannot browse Drive
+- Rotate the service account key periodically via GCP IAM & Admin → Service Accounts
+- For production use, replace the JSON key with **Workload Identity Federation**
+  (no long-lived credentials) — see Google's
+  [GitHub Actions OIDC guide](https://cloud.google.com/blog/products/identity-security/enabling-keyless-authentication-from-github-actions)
+
+---
+
+## Expanding to org-wide coverage (Option B)
+
+Currently all helpdesk tickets must be filed in `JCSDA-internal/.github`
+because GitHub Actions workflows only fire for events in the repo they live in.
+Partners in other repos are directed here via the `contact_links` entry in
+`ISSUE_TEMPLATE/config.yaml`.
+
+When moving to full operational use, the plan is to add an **org-level
+webhook** routing `issues` events to an AWS Lambda (following the existing
+pattern in `github-admin/webhooks/`). This will allow tickets to be filed in
+any JCSDA-Internal repo while still syncing to the same sheet. The `repo`
+column already in the spreadsheet schema handles the multi-repo case without
+any schema changes.

.github/helpdesk/org_assignee_map.json

@@ -0,0 +1,14 @@
+{
+  "_readme": "Map partner organization names to their JCSDA GitHub liaison username. Keys are matched case-insensitively as substrings against the free-text 'Requesting Organization' field. Replace PLACEHOLDER values with real GitHub usernames before deploying.",
+
+  "default_assignee": "gibbsp",
+
+  "NOAA/NWS/EMC":   "gibbsp",
+  "NOAA/GFDL":      "gibbsp",
+  "NRL Monterey":   "gibbsp",
+  "NASA/GMAO":      "gibbsp",
+  "AFWA":           "gibbsp",
+  "Navy":           "gibbsp",
+  "Air Force":      "gibbsp",
+  "University":     "gibbsp"
+}