Add GitHub CI workflow for the full test pipeline

[aubrypaul]

Context

We recently added test coverage for configurable Apps Script authentication modes, including API key and Vertex AI authentication paths.

The test changes are being handled separately first. This issue tracks the follow-up work to add GitHub-side CI support for the full test pipeline, not only the authentication-mode tests.

Goal

Add a GitHub Actions workflow that runs the project’s full test pipeline in CI, while supporting configurable authentication-mode tests safely.

The workflow should validate the codebase broadly, and include the auth-mode tests only when explicitly enabled and properly configured.

Scope

Implement a GitHub Actions workflow that supports:

• running the standard test pipeline in CI;
• running syntax or static validation checks where applicable;
• running Apps Script test functions through clasp where applicable;
• manual workflow dispatch;
• optional automatic triggers on pull requests and pushes, if appropriate;
• inputs or configuration switches to enable or disable API key auth tests;
• inputs or configuration switches to enable or disable Vertex AI auth tests;
• repository-level or environment-level configuration overrides;
• validation of enabled auth modes;
• validation that required secrets are present before running enabled auth tests;
• secret-safe clasp setup;
• execution of the selected Apps Script tests;
• clear skip logs when an optional auth mode is disabled;
• clear failure messages when an enabled auth mode is missing credentials.

Expected behavior

The default CI pipeline should run the normal test suite without requiring authentication secrets.

Authentication-mode tests should be opt-in or configuration-based, so the main test pipeline can still run safely in environments where secrets are unavailable.

When API key tests are disabled, CI should skip them explicitly.

When Vertex AI tests are disabled, CI should skip them explicitly.

When an auth mode is enabled but the required secrets are missing, CI should fail clearly without leaking secret values.

When the required secrets are present, CI should run the corresponding Apps Script smoke tests as part of the broader test pipeline.

Documentation

Add documentation covering:

• what the full CI test pipeline runs;
• when the workflow runs automatically;
• how to run the workflow manually;
• required GitHub secrets for optional auth-mode tests;
• optional repository or environment variables;
• behavior of each enable or disable switch;
• skip behavior;
• missing-credential failure behavior;
• how CI configuration maps to local Apps Script Script Properties setup.

Out of scope

• Changing production authentication behavior;
• adding new authentication modes;
• logging or exposing secret values;
• requiring secrets for the default test pipeline;
• making optional external-auth smoke tests mandatory for every PR unless explicitly decided.

Acceptance criteria

• A GitHub Actions workflow exists for the full test pipeline.
• The standard tests run without requiring auth secrets.
• The workflow can be triggered manually.
• The workflow can run on pull requests and/or pushes if configured.
• API key and Vertex AI auth tests can be enabled or disabled independently.
• Missing required secrets for enabled optional tests produce clear failures.
• Disabled optional auth modes produce clear skip logs.
• Secrets are never printed in logs.
• Documentation explains CI setup and usage.
• Existing local test behavior remains unchanged.

[aubrypaul]

@coderabbitai plan this issue for codex

[coderabbitai]

Coding Plan

Summary

• Establish clasp infrastructure with manifest and configuration files that support CI secret injection, keeping the repository generic and not tied to a specific Apps Script project
• Create a GitHub Actions workflow with syntax validation as the default always-running pipeline (independent of clasp auth) and Apps Script test execution as opt-in based on workflow inputs
• Implement robust secret validation and clasp authentication validity checks that fail clearly when enabled auth modes lack required credentials or have invalid/expired credentials, while never exposing secret values
• Add comprehensive documentation mapping CI configuration to local development patterns, including detailed credential lifecycle and troubleshooting guidance

Design Choices

Design Choice 1: How to handle Script ID for clasp

Options Considered:

1. Commit the scriptId directly in .clasp.json (exposes project ID, ties repo to one project)
2. Use a GitHub secret SCRIPT_ID and generate .clasp.json dynamically in CI

Chosen Option: 2

Rationale: Using a secret keeps the repository generic and allows different forks/environments to use their own Apps Script projects without modifying committed files.

Design Choice 2: What constitutes "standard tests" vs "auth-mode tests"

Options Considered:

1. Treat syntax validation as the "standard pipeline" and all Apps Script tests as opt-in auth-mode tests
2. Assume some tests exist that don't require auth (none visible in current code)

Chosen Option: 1

Rationale: Syntax/static validation runs as the default pipeline without secrets; actual Apps Script test execution is opt-in and requires corresponding auth secrets.

Design Choice 3: Granularity of auth-mode inputs

Options Considered:

1. Two inputs: enable-api-key-tests (combines OpenAI + Gemini API keys) and enable-vertex-ai-tests
2. Three inputs: separate toggles for OpenAI, Gemini API key, and Vertex AI

Chosen Option: 1

Rationale: Matches ticket language; OpenAI and Gemini API key tests are conceptually similar (both use API keys vs OAuth), keeping the interface simpler while still allowing Vertex AI to be toggled independently.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Establish Clasp and Project Infrastructure

Add the necessary configuration files to enable clasp-based deployment and remote test execution. These files provide the Apps Script manifest and project mapping that clasp requires.

Task 1: Create Apps Script Manifest

Add the appsscript.json manifest file that defines the Apps Script runtime configuration and enables the Execution API for remote function calls.

• Create appsscript.json at the repository root with runtime version, time zone, and executionApi block set to appropriate access level
• Include required OAuth scopes for the library (e.g., cloud-platform for Vertex AI support)
• Configure the manifest to work with clasp push and clasp run-function commands

Task 2: Create Clasp Configuration Template

Add clasp configuration that works with CI secret injection for the script ID.

• Create .clasp.json.example as a template showing the expected structure with placeholder scriptId
• Document in comments that the actual .clasp.json is generated in CI from the SCRIPT_ID secret
• Add .clasp.json to .gitignore to prevent accidental commits of real script IDs

Task 3: Add Clasp Ignore File

Create a .claspignore file to exclude non-Apps Script files from being pushed.

• Exclude documentation files (README.md, LICENSE)
• Exclude CI configuration (.github/, .clasp.json.example)
• Exclude any future Node.js tooling files if added
• Keep only the src/ directory contents for pushing

🤖 Prompt for AI agents

Set up the clasp and Apps Script project infrastructure files needed for
CI-based deployment and remote test execution.

**Task 1: Create `appsscript.json` at the repository root**
- Include the runtime version, time zone, and an `executionApi` block set to the
appropriate access level
- Include required OAuth scopes (e.g., `cloud-platform` for Vertex AI support)
- Ensure it is compatible with `clasp push` and `clasp run` commands

**Task 2: Create `.clasp.json.example`**
- Provide a template showing the expected JSON structure with a placeholder
`scriptId`
- Add a comment (or README note) indicating the actual `.clasp.json` is
generated dynamically in CI from the `SCRIPT_ID` secret
- Add `.clasp.json` to `.gitignore` to prevent accidental commits of real script
IDs

**Task 3: Create `.claspignore`**
- Exclude documentation files: `README.md`, `LICENSE`
- Exclude CI configuration: `.github/`, `.clasp.json.example`
- Exclude any future Node.js tooling files
- Allow only the `src/` directory contents to be pushed to Apps Script

Phase 2: Create GitHub Actions Workflow

Implement the main CI workflow with configurable triggers, auth-mode inputs, secret validation, and conditional test execution.

Task 1: Create Workflow File with Triggers and Inputs

Set up the workflow file structure with appropriate event triggers and workflow inputs for auth-mode configuration.

• Create .github/workflows/test.yml (or ci.yml) as the main workflow file
• Configure workflow_dispatch trigger with boolean inputs for enable-api-key-tests and enable-vertex-ai-tests (both defaulting to false)
• Add optional pull_request and push triggers with sensible branch filters (e.g., main branch, PR to main)
• Define environment variables section for referencing secrets

Task 2: Implement Syntax Validation Job

Add a job that performs static validation of the Apps Script source files without requiring any secrets. This job is independent of clasp authentication and always runs regardless of clasp credential availability or validity.

• Create a job that checks out the repository and validates JavaScript syntax
• Use Node.js to parse .gs files and detect syntax errors (e.g., using node --check or a simple parse script)
• This job should always run and pass without any secrets configured, independent of any clasp setup or authentication status
• Provide clear output indicating which files were validated

Task 3: Implement Clasp Setup with Secret and Authentication Validation

Add steps to configure clasp authentication and validate both that required secrets are present and that credentials are valid before attempting to run tests.

• Install clasp as a global npm package in the runner
• Check for presence of CLASPRC_JSON secret; if missing, log clearly (e.g., "CLASPRC_JSON secret not configured - skipping clasp setup") and set a job output flag indicating clasp is unavailable
• Generate .clasp.json from SCRIPT_ID secret
• Recreate ~/.clasprc.json from the CLASPRC_JSON secret for clasp authentication
• Run clasp login --status as a distinct authentication validity check step after credential setup
• If clasp login --status fails, produce a clear error message distinguishing "credentials present but invalid/expired" from "credentials missing" (e.g., "Clasp credentials are present but authentication failed - credentials may be expired or revoked. Please regenerate CLASPRC_JSON.")
• Set a job output flag indicating whether clasp authentication is valid for use by downstream steps

Task 4: Implement Secret Validation for Auth Modes

Add validation logic that checks whether required secrets are present when an auth mode is enabled.

• When enable-api-key-tests is true, verify OPEN_AI_API_KEY and GEMINI_API_KEY secrets exist
• When enable-vertex-ai-tests is true, verify Vertex AI credentials are configured (project ID, service account, etc.)
• If an enabled mode is missing required secrets, fail the workflow with a clear error message (without logging secret values)
• Use GitHub Actions secret presence checks (e.g., ${{ secrets.SECRET_NAME != '' }})

Task 5: Implement Test Execution with Conditional Failure Logic

Add conditional steps that run the appropriate test functions based on enabled auth modes, with different failure behavior depending on whether auth tests were explicitly requested.

• Implement conditional behavior based on whether any auth-mode tests are explicitly enabled:
  • When NO auth tests are enabled (enable-api-key-tests=false AND enable-vertex-ai-tests=false) AND clasp credentials are missing or invalid: skip all clasp-dependent steps silently, syntax validation remains green, workflow succeeds
  • When ANY auth test is explicitly enabled (enable-api-key-tests=true OR enable-vertex-ai-tests=true) AND clasp setup fails (CLASPRC_JSON missing, SCRIPT_ID missing, or clasp login --status fails): hard fail the workflow with a clear, actionable error message (e.g., "Auth tests were requested but clasp authentication failed. Ensure CLASPRC_JSON and SCRIPT_ID secrets are configured and credentials are valid.")
• When API key tests are enabled and all validations pass, use clasp run-function to execute relevant test functions
• When Vertex AI tests are enabled and configured, run the corresponding test functions
• When an auth mode is disabled, output a clear skip message (e.g., "Skipping API key tests: not enabled via workflow input")
• Capture test output and handle failures appropriately
• Ensure no secret values appear in logs (mask them if necessary)

Task 6: Implement Test Preparation Script

Create a helper script that prepares the test environment by injecting API keys as script-level variables before pushing to Apps Script.

• Create a script (shell or Node.js) in .github/scripts/ that modifies testFunctions.gs to include API key variable definitions
• Read API keys from environment variables (sourced from secrets)
• Inject them as const declarations at the top of the test file
• This modified file is pushed to Apps Script for test execution, then never committed
• Ensure the script handles missing keys gracefully based on which auth modes are enabled

🤖 Prompt for AI agents

Implement the main GitHub Actions CI workflow file along with a test preparation
helper script. The goal is a fully configurable workflow with always-on syntax
validation (independent of clasp auth), optional clasp-based Apps Script test
execution, and clear skip/failure messaging including conditional failure logic
based on user intent.

**Task 1: Create `.github/workflows/test.yml` (or `ci.yml`)**
- Add `workflow_dispatch` trigger with two boolean inputs:
`enable-api-key-tests` and `enable-vertex-ai-tests`, both defaulting to `false`
- Add optional `pull_request` and `push` triggers filtered to the `main` branch
- Define an environment variables section referencing secrets where needed

**Task 2: Syntax Validation Job**
- Add a job that always runs with no secret dependency and independent of any
clasp setup or authentication status
- Check out the repository
- Use Node.js with `node --check` (or a simple parse script) to validate all
`.gs` source files for JavaScript syntax errors
- Output clearly which files were validated

**Task 3: Clasp Setup and Authentication Validation Steps**
- Install `clasp` as a global npm package
- Check for presence of `CLASPRC_JSON` secret; if absent, log a clear message
(e.g., "CLASPRC_JSON secret not configured - skipping clasp setup") and set a
job output flag indicating clasp is unavailable
- Generate `.clasp.json` dynamically from the `SCRIPT_ID` secret
- Recreate `~/.clasprc.json` from the `CLASPRC_JSON` secret
- Run `clasp login --status` as a distinct authentication validity check step
after credential setup
- If `clasp login --status` fails, produce a clear error message that
distinguishes "credentials present but invalid/expired" from "credentials
missing" (e.g., "Clasp credentials are present but authentication failed -
credentials may be expired or revoked. Please regenerate CLASPRC_JSON.")
- Set a job output flag indicating whether clasp authentication is valid for use
by downstream steps

**Task 4: Secret Validation for Auth Modes**
- If `enable-api-key-tests` is `true`, verify both `OPEN_AI_API_KEY` and
`GEMINI_API_KEY` are non-empty using `${{ secrets.SECRET_NAME != '' }}`; fail
with a clear error message if either is missing (do not log secret values)
- If `enable-vertex-ai-tests` is `true`, verify required Vertex AI credentials
(project ID, service account, etc.) are present; fail clearly if missing

**Task 5: Conditional Test Execution with Failure Logic**
- Implement conditional behavior based on whether any auth-mode tests are
explicitly enabled:
- When NO auth tests are enabled (`enable-api-key-tests=false` AND
`enable-vertex-ai-tests=false`) AND clasp credentials are missing or invalid:
skip all clasp-dependent steps silently; syntax validation remains green;
workflow succeeds
- When ANY auth test is explicitly enabled (`enable-api-key-tests=true` OR
`enable-vertex-ai-tests=true`) AND clasp setup fails (`CLASPRC_JSON` missing,
`SCRIPT_ID` missing, or `clasp login --status` fails): hard fail the workflow
with a clear, actionable error message (e.g., "Auth tests were requested but
clasp authentication failed. Ensure CLASPRC_JSON and SCRIPT_ID secrets are
configured and credentials are valid.")
- When API key tests are enabled and all validations pass, invoke `clasp
run-function` for the relevant test functions
- When Vertex AI tests are enabled and configured, run corresponding test
functions
- When a mode is disabled, output a clear skip message (e.g., `"Skipping API key
tests: not enabled via workflow input"`)
- Capture test output; handle and surface failures appropriately; mask secret
values in logs

**Task 6: Create `.github/scripts/prepare-tests.sh` (or `.js`)**
- Read API key values from environment variables (populated from secrets)
- Inject them as `const` declarations at the top of `src/testFunctions.gs`
- The modified file is used for the clasp push and never committed
- Handle missing keys gracefully based on which auth modes are active

Phase 3: Documentation

Add comprehensive documentation explaining CI setup, required secrets, workflow inputs, and behavior.

Task 1: Add CI Documentation Section to README

Update the README with a dedicated section explaining the CI workflow and how to use it.

• Add a "CI/CD" or "Continuous Integration" section to README.md
• Explain what the workflow validates (syntax checking, optional Apps Script test execution)
• Document when the workflow runs automatically (PR, push to main) vs manual dispatch
• Explain how to trigger the workflow manually via GitHub Actions UI

Task 2: Document Required Secrets

Add documentation listing all GitHub secrets needed for the full CI pipeline, with comprehensive lifecycle information for clasp credentials.

• Document CLASPRC_JSON with full lifecycle coverage:
  • How to generate it locally by running clasp login and locating the resulting ~/.clasprc.json file
  • How to copy its contents and store as a GitHub repository secret
  • Conditions that require regeneration: clasp authentication failures in CI, changing the Google account used for authentication, changes to required OAuth scopes, credential revocation by Google, or token expiration
  • Note that credentials may expire or be revoked without warning, requiring periodic regeneration
• Document SCRIPT_ID: the Apps Script project ID for the test deployment
• Document OPEN_AI_API_KEY and GEMINI_API_KEY: required when API key tests are enabled
• Document Vertex AI secrets if applicable (e.g., GCP_PROJECT_ID, GCP_REGION, service account credentials)
• Include instructions for obtaining each secret value

Task 3: Document Workflow Inputs and Behavior

Explain the workflow dispatch inputs and the resulting behavior for each configuration.

• Document enable-api-key-tests input: what it controls, what secrets it requires, default value
• Document enable-vertex-ai-tests input: what it controls, what secrets it requires, default value
• Explain skip behavior: what users will see in logs when an auth mode is disabled
• Explain failure behavior: what happens when an enabled mode is missing secrets
• Provide example scenarios (e.g., "To run only API key tests, set enable-api-key-tests to true and ensure secrets X, Y are configured")

Task 4: Document CI to Local Setup Mapping

Explain how the CI configuration relates to local development and testing.

• Map GitHub secrets to the local script-level variables expected by the test functions
• Explain that locally, users define OPEN_AI_API_KEY etc. as variables in their Apps Script project
• Explain that CI injects these values automatically before pushing to the test project
• Note any differences between local and CI test execution

Task 5: Add Troubleshooting Section

Create a dedicated troubleshooting section for diagnosing and resolving clasp credential and CI failures.

• Document how to detect clasp credential failures in CI logs (look for "credentials present but invalid/expired" messages, clasp login --status failures)
• Provide step-by-step instructions for regenerating CLASPRC_JSON locally:
  • Run clasp logout to clear existing credentials
  • Run clasp login and complete the OAuth flow
  • Locate the new ~/.clasprc.json file
  • Copy the file contents
• Explain how to update the GitHub secret with the new CLASPRC_JSON value
• Document common failure scenarios and their resolutions (e.g., "401 Unauthorized" indicates expired tokens, "Script not found" indicates incorrect SCRIPT_ID)
• Include guidance on verifying clasp works locally before updating CI secrets

🤖 Prompt for AI agents

Update `README.md` with a comprehensive CI/CD documentation section. The goal is
to give users everything they need to understand, configure, and troubleshoot
the GitHub Actions workflow.

**Task 1: Add a "CI/CD" or "Continuous Integration" section to `README.md`**
- Describe what the workflow validates: syntax checking (always runs,
independent of clasp auth) and optional Apps Script test execution
- Document automatic triggers: push to `main` and PRs targeting `main`
- Explain how to trigger the workflow manually via the GitHub Actions UI

**Task 2: Document Required Secrets**
- `CLASPRC_JSON` with full lifecycle coverage:
- How to generate it locally: run `clasp login` and locate the resulting
`~/.clasprc.json` file
  - How to copy its contents and store as a GitHub repository secret
- Conditions that require regeneration: clasp authentication failures in CI,
changing the Google account, changes to required OAuth scopes, credential
revocation by Google, or token expiration
- Note that credentials may expire or be revoked without warning, requiring
periodic regeneration
- `SCRIPT_ID`: the Apps Script project ID for the test deployment
- `OPEN_AI_API_KEY` and `GEMINI_API_KEY`: required when `enable-api-key-tests`
is enabled
- Vertex AI secrets (e.g., `GCP_PROJECT_ID`, `GCP_REGION`, service account
credentials): required when `enable-vertex-ai-tests` is enabled
- Include instructions for obtaining each secret value

**Task 3: Document Workflow Inputs and Behavior**
- `enable-api-key-tests`: what it controls, required secrets (`OPEN_AI_API_KEY`,
`GEMINI_API_KEY`), default (`false`)
- `enable-vertex-ai-tests`: what it controls, required Vertex AI secrets,
default (`false`)
- Skip behavior: describe what users see in logs when a mode is disabled
- Failure behavior: describe what happens when an enabled mode is missing
secrets
- Provide example scenarios (e.g., "To run only API key tests, set
`enable-api-key-tests` to true and ensure secrets X, Y are configured")

**Task 4: Document CI to Local Setup Mapping**
- Map each GitHub secret to its corresponding local script-level variable in the
Apps Script project
- Explain that locally users define `OPEN_AI_API_KEY` etc. as variables directly
in their Apps Script project
- Explain that CI injects these values automatically via the prepare-tests
script before pushing
- Note any differences between local and CI test execution

**Task 5: Add Troubleshooting Section**
- Explain how to detect clasp credential failures in CI logs (look for
"credentials present but invalid/expired" messages and `clasp login --status`
failures)
- Provide step-by-step instructions for regenerating `CLASPRC_JSON` locally:
  - Run `clasp logout` to clear existing credentials
  - Run `clasp login` and complete the OAuth flow
  - Locate the new `~/.clasprc.json` file and copy its contents
- Explain how to update the GitHub secret with the new `CLASPRC_JSON` value
- Document common failure scenarios and resolutions (e.g., "401 Unauthorized" =
expired tokens; "Script not found" = incorrect `SCRIPT_ID`)
- Include guidance on verifying clasp works locally before updating CI secrets

Research

This is a minimal Google Apps Script library with no existing CI/CD infrastructure, no clasp configuration, and no package.json or Node.js tooling. The codebase consists of src/code.gs (main library) and src/testFunctions.gs (manual test functions). Tests are plain Apps Script functions that use console.log() output and require API keys (OPEN_AI_API_KEY, GEMINI_API_KEY) defined as script-level variables. Three authentication modes exist: OpenAI API key, Gemini API key, and Vertex AI OAuth. Running tests remotely requires clasp with proper authentication and an "API executable" deployment.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the clasp and Apps Script project infrastructure files needed for
CI-based deployment and remote test execution.

**Task 1: Create `appsscript.json` at the repository root**
- Include the runtime version, time zone, and an `executionApi` block set to the
appropriate access level
- Include required OAuth scopes (e.g., `cloud-platform` for Vertex AI support)
- Ensure it is compatible with `clasp push` and `clasp run` commands

**Task 2: Create `.clasp.json.example`**
- Provide a template showing the expected JSON structure with a placeholder
`scriptId`
- Add a comment (or README note) indicating the actual `.clasp.json` is
generated dynamically in CI from the `SCRIPT_ID` secret
- Add `.clasp.json` to `.gitignore` to prevent accidental commits of real script
IDs

**Task 3: Create `.claspignore`**
- Exclude documentation files: `README.md`, `LICENSE`
- Exclude CI configuration: `.github/`, `.clasp.json.example`
- Exclude any future Node.js tooling files
- Allow only the `src/` directory contents to be pushed to Apps Script
===============================================================================

Task: 2

Implement the main GitHub Actions CI workflow file along with a test preparation
helper script. The goal is a fully configurable workflow with always-on syntax
validation (independent of clasp auth), optional clasp-based Apps Script test
execution, and clear skip/failure messaging including conditional failure logic
based on user intent.

**Task 1: Create `.github/workflows/test.yml` (or `ci.yml`)**
- Add `workflow_dispatch` trigger with two boolean inputs:
`enable-api-key-tests` and `enable-vertex-ai-tests`, both defaulting to `false`
- Add optional `pull_request` and `push` triggers filtered to the `main` branch
- Define an environment variables section referencing secrets where needed

**Task 2: Syntax Validation Job**
- Add a job that always runs with no secret dependency and independent of any
clasp setup or authentication status
- Check out the repository
- Use Node.js with `node --check` (or a simple parse script) to validate all
`.gs` source files for JavaScript syntax errors
- Output clearly which files were validated

**Task 3: Clasp Setup and Authentication Validation Steps**
- Install `clasp` as a global npm package
- Check for presence of `CLASPRC_JSON` secret; if absent, log a clear message
(e.g., "CLASPRC_JSON secret not configured - skipping clasp setup") and set a
job output flag indicating clasp is unavailable
- Generate `.clasp.json` dynamically from the `SCRIPT_ID` secret
- Recreate `~/.clasprc.json` from the `CLASPRC_JSON` secret
- Run `clasp login --status` as a distinct authentication validity check step
after credential setup
- If `clasp login --status` fails, produce a clear error message that
distinguishes "credentials present but invalid/expired" from "credentials
missing" (e.g., "Clasp credentials are present but authentication failed -
credentials may be expired or revoked. Please regenerate CLASPRC_JSON.")
- Set a job output flag indicating whether clasp authentication is valid for use
by downstream steps

**Task 4: Secret Validation for Auth Modes**
- If `enable-api-key-tests` is `true`, verify both `OPEN_AI_API_KEY` and
`GEMINI_API_KEY` are non-empty using `${{ secrets.SECRET_NAME != '' }}`; fail
with a clear error message if either is missing (do not log secret values)
- If `enable-vertex-ai-tests` is `true`, verify required Vertex AI credentials
(project ID, service account, etc.) are present; fail clearly if missing

**Task 5: Conditional Test Execution with Failure Logic**
- Implement conditional behavior based on whether any auth-mode tests are
explicitly enabled:
- When NO auth tests are enabled (`enable-api-key-tests=false` AND
`enable-vertex-ai-tests=false`) AND clasp credentials are missing or invalid:
skip all clasp-dependent steps silently; syntax validation remains green;
workflow succeeds
- When ANY auth test is explicitly enabled (`enable-api-key-tests=true` OR
`enable-vertex-ai-tests=true`) AND clasp setup fails (`CLASPRC_JSON` missing,
`SCRIPT_ID` missing, or `clasp login --status` fails): hard fail the workflow
with a clear, actionable error message (e.g., "Auth tests were requested but
clasp authentication failed. Ensure CLASPRC_JSON and SCRIPT_ID secrets are
configured and credentials are valid.")
- When API key tests are enabled and all validations pass, invoke `clasp
run-function` for the relevant test functions
- When Vertex AI tests are enabled and configured, run corresponding test
functions
- When a mode is disabled, output a clear skip message (e.g., `"Skipping API key
tests: not enabled via workflow input"`)
- Capture test output; handle and surface failures appropriately; mask secret
values in logs

**Task 6: Create `.github/scripts/prepare-tests.sh` (or `.js`)**
- Read API key values from environment variables (populated from secrets)
- Inject them as `const` declarations at the top of `src/testFunctions.gs`
- The modified file is used for the clasp push and never committed
- Handle missing keys gracefully based on which auth modes are active
===============================================================================

Task: 3

Update `README.md` with a comprehensive CI/CD documentation section. The goal is
to give users everything they need to understand, configure, and troubleshoot
the GitHub Actions workflow.

**Task 1: Add a "CI/CD" or "Continuous Integration" section to `README.md`**
- Describe what the workflow validates: syntax checking (always runs,
independent of clasp auth) and optional Apps Script test execution
- Document automatic triggers: push to `main` and PRs targeting `main`
- Explain how to trigger the workflow manually via the GitHub Actions UI

**Task 2: Document Required Secrets**
- `CLASPRC_JSON` with full lifecycle coverage:
- How to generate it locally: run `clasp login` and locate the resulting
`~/.clasprc.json` file
  - How to copy its contents and store as a GitHub repository secret
- Conditions that require regeneration: clasp authentication failures in CI,
changing the Google account, changes to required OAuth scopes, credential
revocation by Google, or token expiration
- Note that credentials may expire or be revoked without warning, requiring
periodic regeneration
- `SCRIPT_ID`: the Apps Script project ID for the test deployment
- `OPEN_AI_API_KEY` and `GEMINI_API_KEY`: required when `enable-api-key-tests`
is enabled
- Vertex AI secrets (e.g., `GCP_PROJECT_ID`, `GCP_REGION`, service account
credentials): required when `enable-vertex-ai-tests` is enabled
- Include instructions for obtaining each secret value

**Task 3: Document Workflow Inputs and Behavior**
- `enable-api-key-tests`: what it controls, required secrets (`OPEN_AI_API_KEY`,
`GEMINI_API_KEY`), default (`false`)
- `enable-vertex-ai-tests`: what it controls, required Vertex AI secrets,
default (`false`)
- Skip behavior: describe what users see in logs when a mode is disabled
- Failure behavior: describe what happens when an enabled mode is missing
secrets
- Provide example scenarios (e.g., "To run only API key tests, set
`enable-api-key-tests` to true and ensure secrets X, Y are configured")

**Task 4: Document CI to Local Setup Mapping**
- Map each GitHub secret to its corresponding local script-level variable in the
Apps Script project
- Explain that locally users define `OPEN_AI_API_KEY` etc. as variables directly
in their Apps Script project
- Explain that CI injects these values automatically via the prepare-tests
script before pushing
- Note any differences between local and CI test execution

**Task 5: Add Troubleshooting Section**
- Explain how to detect clasp credential failures in CI logs (look for
"credentials present but invalid/expired" messages and `clasp login --status`
failures)
- Provide step-by-step instructions for regenerating `CLASPRC_JSON` locally:
  - Run `clasp logout` to clear existing credentials
  - Run `clasp login` and complete the OAuth flow
  - Locate the new `~/.clasprc.json` file and copy its contents
- Explain how to update the GitHub secret with the new `CLASPRC_JSON` value
- Document common failure scenarios and resolutions (e.g., "401 Unauthorized" =
expired tokens; "Script not found" = incorrect `SCRIPT_ID`)
- Include guidance on verifying clasp works locally before updating CI secrets

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[aubrypaul]

@coderabbitai please update the plan to account for clasp credential expiration / invalidation.

In practice, I sometimes need to run clasp login again locally, so the CI plan should explicitly handle the case where the stored CLASPRC_JSON secret becomes invalid.

Please include:

• a clasp login --status or equivalent authentication check before any clasp-dependent step;
• a clear failure message when clasp credentials are invalid, without printing secrets;
• documentation explaining that CLASPRC_JSON is generated from a local clasp login, stored as a GitHub secret, and only needs to be regenerated when authentication fails, the Google account changes, required scopes change, or credentials are revoked/expired;
• a troubleshooting section explaining how to regenerate CLASPRC_JSON and update the GitHub secret;
• ensure default syntax/static validation still runs even if clasp authentication is unavailable.

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[aubrypaul]

@coderabbitai one more refinement: please distinguish skip vs failure behavior for clasp authentication.

If no Apps Script/auth-mode tests are enabled, missing or invalid clasp credentials should skip clasp-dependent steps while keeping the default syntax/static validation green.

But if enable-api-key-tests=true or enable-vertex-ai-tests=true, missing/invalid CLASPRC_JSON, missing SCRIPT_ID, or failed clasp login --status should fail the workflow clearly, because the user explicitly requested Apps Script tests.

Please update the plan so clasp auth failure is only a skip when clasp-dependent tests are not requested, and a hard failure when any clasp-dependent test mode is enabled.

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!