fix(ci): explicitly define secrets in reusable workflows (#961)

* fix(ci): explicitly define secrets in reusable workflows

Resolves the "Unrecognized named-value: 'secrets'" validation error in GitHub Actions. Reusable workflows triggered via `workflow_call` must explicitly declare the secrets they expect to receive, even when `secrets: inherit` is used by the caller.
Updates:
 - .github/workflows/gemini-triage.yml
 - .github/workflows/gemini-review.yml
 - .github/workflows/gemini-invoke.yml

* fix(ci): remove quotes from 'inherit' in secrets

* fix(ci): make secrets optional for Vertex AI support

* feat(ci): add workflow_dispatch for manual testing

* docs: add GitHub Agent workflow details to AGENTS.md and README

Author: awaemmanuel

.github/workflows/gemini-dispatch.yml

@@ -1,6 +1,24 @@
 name: '🔀 Gemini Dispatch'
 
 on:
+  workflow_dispatch:
+    inputs:
+      command:
+        description: 'Command to run'
+        required: true
+        type: choice
+        options:
+          - review
+          - triage
+          - invoke
+      issue_number:
+        description: 'Issue or PR number to act on'
+        required: true
+        type: string
+      additional_context:
+        description: 'Additional context/prompt'
+        required: false
+        type: string
   pull_request_review_comment:
     types:
       - 'created'
@@ -57,6 +75,8 @@ jobs:
       ) || (
         github.event_name == 'issues' &&
         contains(fromJSON('["opened", "reopened"]'), github.event.action)
+      ) || (
+        github.event_name == 'workflow_dispatch'
       )
     runs-on: 'ubuntu-latest'
     permissions:
@@ -67,7 +87,7 @@ jobs:
       command: '${{ steps.extract_command.outputs.command }}'
       request: '${{ steps.extract_command.outputs.request }}'
       additional_context: '${{ steps.extract_command.outputs.additional_context }}'
-      issue_number: '${{ github.event.pull_request.number || github.event.issue.number }}'
+      issue_number: '${{ github.event.pull_request.number || github.event.issue.number || inputs.issue_number }}'
     steps:
       - name: 'Mint identity token'
         id: 'mint_identity_token'
@@ -87,10 +107,22 @@ jobs:
         env:
           EVENT_TYPE: '${{ github.event_name }}.${{ github.event.action }}'
           REQUEST: '${{ github.event.comment.body || github.event.review.body || github.event.issue.body }}'
+          INPUT_COMMAND: '${{ inputs.command }}'
+          INPUT_CONTEXT: '${{ inputs.additional_context }}'
         with:
           script: |
             const request = process.env.REQUEST;
-            const eventType = process.env.EVENT_TYPE
+            const eventType = process.env.EVENT_TYPE;
+            const inputCommand = process.env.INPUT_COMMAND;
+            const inputContext = process.env.INPUT_CONTEXT;
+
+            if (inputCommand) {
+               core.setOutput('command', inputCommand);
+               core.setOutput('additional_context', inputContext || '');
+               core.setOutput('request', `Manual dispatch: ${inputCommand}`);
+               return;
+            }
+
             core.setOutput('request', request);
 
             if (request.startsWith("@gemini-cli /review")) {
@@ -114,7 +146,7 @@ jobs:
       - name: 'Acknowledge request'
         env:
           GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
-          ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
+          ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number || inputs.issue_number }}'
           MESSAGE: |-
             🤖 Hi @${{ github.actor }}, I've received your request, and I'm working on it now! You can track my progress [in the logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for more details.
           REPOSITORY: '${{ github.repository }}'
@@ -135,7 +167,7 @@ jobs:
       pull-requests: 'write'
     with:
       additional_context: '${{ needs.dispatch.outputs.additional_context }}'
-    secrets: 'inherit'
+    secrets: inherit
 
   triage:
     needs: 'dispatch'
@@ -149,7 +181,7 @@ jobs:
       pull-requests: 'write'
     with:
       additional_context: '${{ needs.dispatch.outputs.additional_context }}'
-    secrets: 'inherit'
+    secrets: inherit
 
   invoke:
     needs: 'dispatch'
@@ -163,7 +195,7 @@ jobs:
       pull-requests: 'write'
     with:
       additional_context: '${{ needs.dispatch.outputs.additional_context }}'
-    secrets: 'inherit'
+    secrets: inherit
 
   fallthrough:
     needs:
@@ -194,7 +226,7 @@ jobs:
       - name: 'Send failure comment'
         env:
           GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
-          ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
+          ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number || inputs.issue_number }}'
           MESSAGE: |-
             🤖 I'm sorry @${{ github.actor }}, but I was unable to process your request. Please [see the logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for more details.
           REPOSITORY: '${{ github.repository }}'

.github/workflows/gemini-invoke.yml

@@ -7,6 +7,13 @@ on:
         type: 'string'
         description: 'Any additional context from the request'
         required: false
+    secrets:
+      GEMINI_API_KEY:
+        required: false
+      GOOGLE_API_KEY:
+        required: false
+      APP_PRIVATE_KEY:
+        required: false
 
 concurrency:
   group: '${{ github.workflow }}-invoke-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number }}'

.github/workflows/gemini-review.yml

@@ -7,6 +7,13 @@ on:
         type: 'string'
         description: 'Any additional context from the request'
         required: false
+    secrets:
+      GEMINI_API_KEY:
+        required: false
+      GOOGLE_API_KEY:
+        required: false
+      APP_PRIVATE_KEY:
+        required: false
 
 concurrency:
   group: '${{ github.workflow }}-review-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number }}'

.github/workflows/gemini-triage.yml

@@ -7,6 +7,13 @@ on:
         type: 'string'
         description: 'Any additional context from the request'
         required: false
+    secrets:
+      GEMINI_API_KEY:
+        required: false
+      GOOGLE_API_KEY:
+        required: false
+      APP_PRIVATE_KEY:
+        required: false
 
 concurrency:
   group: '${{ github.workflow }}-triage-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number }}'

AGENTS.md

@@ -3,43 +3,106 @@
 This document provides guidelines for AI agents working on the GenMedia Creative Studio codebase.
 
 ## Styling
+
 - Prefer using shared styles from `components/styles.py` for common UI elements and layout structures.
 - Page-specific or component-specific styles that are not reusable can be defined locally within those files.
 
 ## Google Cloud Storage (GCS)
+
 - All interactions with GCS for storing media or other assets should use the `store_to_gcs` utility function located in `common/storage.py`.
 - This function is configurable via `config/default.py` for bucket names.
 
 ## Configuration
+
 - Application-level configuration values, such as model IDs, API keys (though avoid hardcoding keys directly), GCS bucket names, and feature flags, should be defined in `config/default.py`.
 - Access these configurations by importing `cfg = Default()` from `config.default`.
 
 ## State Management
+
 - Global application state (e.g., theme, user information) is managed in `state/state.py`.
 - Page-specific UI state should be defined in corresponding files within the `state/` directory (e.g., `state/imagen_state.py`, `state/veo_state.py`).
 
 ## Error Handling
+
 - For errors that occur during media generation processes and need to be communicated to the user, use the `GenerationError` custom exception defined in `common/error_handling.py`.
 - Display these errors to the user via dialogs or appropriate UI elements.
 - Log detailed errors to the console/server logs for debugging.
 
 ## Adding New Generative Models
+
 - When adding a new generative model capability (e.g., a new type of image model, a different video model):
-    - Add model interaction logic (API calls, request/response handling) to a new file in the `models/` directory (e.g., `models/new_model_name.py`).
-    - Create UI components for controlling the new model in a subdirectory under `components/` (e.g., `components/new_model_name/generation_controls.py`).
-    - Create a new page for the model in `pages/` (e.g., `pages/new_model_name.py`), utilizing the page scaffold and new components.
-    - Define any page-specific state in `state/new_model_name_state.py`.
-    - Add relevant configurations to `config/default.py`.
-    - Update navigation in `config/navigation.json`.
+  - Add model interaction logic (API calls, request/response handling) to a new file in the `models/` directory (e.g., `models/new_model_name.py`).
+  - Create UI components for controlling the new model in a subdirectory under `components/` (e.g., `components/new_model_name/generation_controls.py`).
+  - Create a new page for the model in `pages/` (e.g., `pages/new_model_name.py`), utilizing the page scaffold and new components.
+  - Define any page-specific state in `state/new_model_name_state.py`.
+  - Add relevant configurations to `config/default.py`.
+  - Update navigation in `config/navigation.json`.
 
 ## Metadata
+
 - When storing metadata for generated media, use the `MediaItem` dataclass from `common/metadata.py` and the `add_media_item_to_firestore` function.
 - Ensure all relevant fields in `MediaItem` are populated.
 
 ## Testing
+
 - Write unit tests for utility functions and model interaction logic.
 - Aim to mock external API calls during unit testing.
 - Use `pytest` as the testing framework.
 
 ## Code Quality
+
 - Use `ruff` for code formatting and linting. Ensure code is formatted (`ruff format .`) and linted (`ruff check --fix .`) before submitting changes.
+
+
+## 🤖 GitHub Automation Agents
+
+This repository uses **Google's Gemini CLI** to automate software engineering tasks. Our AI agents assist with code reviews, issue triage, and general maintenance to keep the project moving efficiently.
+
+## Automatic Behaviors
+
+These agents run automatically based on events in the repository.
+
+### 🔎 Code Reviewer
+
+- **Trigger:** When a **Pull Request** is opened.
+
+- **Action:** The agent reviews the code changes (diff), looking for bugs, security issues, and style improvements.
+- **Output:** It posts review comments directly on the PR.
+- **Note:** The agent focuses on the *diff* only and provides constructive feedback. It does not replace human review.
+
+### 📋 Issue Triage
+
+- **Trigger:** When a new **Issue** is opened.
+
+- **Action:** The agent analyzes the title and body of the issue.
+- **Output:** It automatically applies relevant **Labels** (e.g., `bug`, `enhancement`, `question`) to help organize the backlog.
+
+---
+
+## Maintainer Commands
+
+Project maintainers (Owners, Members, Collaborators) can manually invoke the agents using comment commands.
+
+| Command | Description |
+| :--- | :--- |
+| `@gemini-cli /review` | Manually triggers a full code review on the current Pull Request. |
+| `@gemini-cli /triage` | Manually triggers label analysis on the current Issue or PR. |
+| `@gemini-cli [question]` | Ask the agent a question about the codebase or request a specific task.  
+
+*Example:* `@gemini-cli Explain how the authentication flow works.` |
+
+> **Note:** These commands are restricted to project maintainers to prevent abuse and manage costs.
+
+---
+
+## Workflow Architecture
+
+The automation is built on GitHub Actions using a "Router-Worker" pattern:
+
+1. **Dispatch Router (`gemini-dispatch.yml`):** The entry point. It listens for events, validates permissions, and routes the request to the correct worker.
+2. **Worker Workflows:**
+    - `gemini-review.yml`: Handles code analysis.
+    - `gemini-triage.yml`: Handles labeling.
+    - `gemini-invoke.yml`: Handles general Q&A.
+
+This system is powered by the [Gemini CLI](https://github.com/google-github-actions/run-gemini-cli) action.