Use v0 tag for human-facing docs, consistent YAML (#93)

This won't work until we cut a `@v0` floating alias, but we can do that
at any time. We want to make sure people aren't pinning to `@main` (from
experience).

This also moves the workflows from the root into an `examples/`
directory, which is more expected.

Author: sethvargo

.github/workflows/gemini-cli.yml

@@ -29,7 +29,7 @@ permissions:
 jobs:
   gemini-cli:
     # This condition is complex to ensure we only run when explicitly invoked.
-    if: |
+    if: |-
       github.event_name == 'workflow_dispatch' ||
       (
         github.event_name == 'issues' && github.event.action == 'opened' &&
@@ -200,7 +200,7 @@ jobs:
           } >> "${GITHUB_OUTPUT}"
 
       - name: 'Set up git user for commits'
-        run: |
+        run: |-
           git config --global user.name 'gemini-cli[bot]'
           git config --global user.email 'gemini-cli[bot]@users.noreply.github.com'
 
@@ -226,7 +226,7 @@ jobs:
       - name: 'Create new branch for issue'
         if: |-
           ${{  steps.get_context.outputs.is_pr == 'false' }}
-        run: |
+        run: |-
           set -euo pipefail
           BRANCH_NAME="gemini-issue-${{ steps.get_context.outputs.issue_number }}"
           git checkout -b "${BRANCH_NAME}"
@@ -239,7 +239,7 @@ jobs:
           ISSUE_NUMBER: '${{ steps.get_context.outputs.issue_number }}'
           REPOSITORY: '${{ github.repository }}'
           REQUEST_TYPE: '${{ steps.get_context.outputs.request_type }}'
-        run: |
+        run: |-
           set -euo pipefail
           MESSAGE=""
           case "${REQUEST_TYPE}" in
@@ -285,7 +285,7 @@ jobs:
           gcp_service_account: '${{ vars.SERVICE_ACCOUNT_EMAIL }}'
           use_vertex_ai: '${{ vars.GOOGLE_GENAI_USE_VERTEXAI }}'
           use_gemini_code_assist: '${{ vars.GOOGLE_GENAI_USE_GCA }}'
-          settings: |
+          settings: |-
             {
               "maxSessionTurns": 50,
               "coreTools": [

.github/workflows/gemini-issue-automated-triage.yml

@@ -120,7 +120,7 @@ jobs:
         uses: 'actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea'
         with:
           github-token: '${{ steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}'
-          script: |
+          script: |-
             github.rest.issues.createComment({
               owner: '${{ github.repository }}'.split('/')[0],
               repo: '${{ github.repository }}'.split('/')[1],

.github/workflows/gemini-pr-review.yml

@@ -403,7 +403,7 @@ jobs:
         uses: 'actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea'
         with:
           github-token: '${{ steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}'
-          script: |
+          script: |-
             github.rest.issues.createComment({
               owner: '${{ github.repository }}'.split('/')[0],
               repo: '${{ github.repository }}'.split('/')[1],

README.md

@@ -35,7 +35,7 @@ Cloud product, please contact [Google Cloud support].**
 
 ## Features
 
-- **Automation**: Trigger workflows based on events (e.g. issue opening) or schedules (e.g. nightly). 
+- **Automation**: Trigger workflows based on events (e.g. issue opening) or schedules (e.g. nightly).
 - **On-demand Collaboration**: Trigger workflows in issue and pull request
   comments by mentioning the [Gemini CLI] (e.g., `@gemini-cli /review`).
 - **Extensible with Tools**: Leverage [Gemini] models' tool-calling capabilities to
@@ -61,16 +61,19 @@ You have two options to set up a workflow:
 
 **Option A: Use setup command (Recommended)**
 1. Start the Gemini CLI:
-   ```bash
+
+   ```shell
    gemini
    ```
+
 2. In the chat interface, type:
+
    ```
    /setup-github
    ```
 
-**Option B: Manually copy workflows** 
-1. Copy the pre-built workflows from the [`/workflows`](./workflows) directory to your repository's `.github/workflows` directory.
+**Option B: Manually copy workflows**
+1. Copy the pre-built workflows from the [`examples/workflows`](./examples/workflows) directory to your repository's `.github/workflows` directory.
 
 ### 4. Try it out!
 
@@ -98,20 +101,20 @@ This action provides several pre-built workflows for different use cases. Each w
 
 This action can be used to triage GitHub Issues automatically or on a schedule.
 For a detailed guide on how to set up the issue triage system, go to the
-[GitHub Issue Triage workflow documentation](./workflows/issue-triage).
+[GitHub Issue Triage workflow documentation](./examples/workflows/issue-triage).
 
 ### Pull Request Review
 
 This action can be used to automatically review pull requests when they are
 opened. For a detailed guide on how to set up the pull request review system,
-go to the [GitHub PR Review workflow documentation](./workflows/pr-review).
+go to the [GitHub PR Review workflow documentation](./examples/workflows/pr-review).
 
 ### Gemini CLI Assistant
 
 This type of action can be used to invoke a general-purpose, conversational Gemini
 AI assistant within the pull requests and issues to perform a wide range of
 tasks. For a detailed guide on how to set up the general-purpose Gemini CLI workflow,
-go to the [Gemini CLI workflow documentation](./workflows/gemini-cli).
+go to the [Gemini CLI workflow documentation](./examples/workflows/gemini-cli).
 
 ### Inputs
 
@@ -166,7 +169,7 @@ We recommend setting the following values as repository variables so they can be
 | `APP_ID`                    | GitHub App ID for custom authentication.               | Variable | No       | Using a custom GitHub App |
 
 
-To add a repository variable: 
+To add a repository variable:
 1) Go to your repository's **Settings > Secrets and variables > Actions > New variable**.
 2) Enter the variable name and value.
 3) Save.
@@ -183,16 +186,17 @@ You can set the following secrets in your repository:
 | `APP_PRIVATE_KEY` | Private key for your GitHub App (PEM format). | No       | Using a custom GitHub App.    |
 
 To add a secret:
-1) Go to your repository's **Settings > Secrets and variables >Actions > New repository secret**. 
-2) Enter the secret name and value.
-3) Save.
+
+1. Go to your repository's **Settings > Secrets and variables >Actions > New repository secret**.
+2. Enter the secret name and value.
+3. Save.
 
 For more information, refer to the
 [official GitHub documentation on creating and using encrypted secrets][secrets].
 
 ## Authentication
 
-This action requires authentication to both Google services (for Gemini AI) and the GitHub API. 
+This action requires authentication to both Google services (for Gemini AI) and the GitHub API.
 
 ### Google Authentication
 

action.yml

@@ -19,12 +19,12 @@ description: |-
 
 inputs:
   prompt:
-    description: |
+    description: |-
       A string passed to the Gemini CLI's [`--prompt` argument](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#command-line-arguments).
     required: false
     default: 'You are a helpful assistant.'
   settings:
-    description: |
+    description: |-
       A JSON string written to `.gemini/settings.json` to configure the CLI's _project_ settings.
       For more details, see the documentation on [settings files](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#settings-files).
     required: false
@@ -67,7 +67,7 @@ runs:
     - name: 'Configure Gemini CLI'
       if: |-
         ${{ inputs.settings != '' }}
-      run: |
+      run: |-
         mkdir -p .gemini/
         echo "${SETTINGS}" > ".gemini/settings.json"
       shell: 'bash'
@@ -138,7 +138,7 @@ runs:
 
     - name: 'Run Gemini CLI'
       id: 'gemini_run'
-      run: |
+      run: |-
         set -e
         GEMINI_RESPONSE=$(gemini --yolo --prompt "${PROMPT}")
         # Set the captured response as a step output, supporting multiline

docs/authentication.md

@@ -49,10 +49,11 @@ This is the simplest method and is suitable for projects that do not require Goo
 #### Example
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
-    prompt: "Explain this code"
-    gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
+    prompt: |-
+      Explain this code
+    gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
 ```
 
 ### Method 2: Authenticating with Google Cloud
@@ -92,7 +93,7 @@ Your user account needs these permissions in the target GCP project to run the s
 Basic setup for your repository:
 
 ```shell
-./scripts/setup_workload_identity.sh --repo OWNER/REPO --project GOOGLE_CLOUD_PROJECT
+./scripts/setup_workload_identity.sh --repo "[OWNER]/[REPO]" --project "[GOOGLE_CLOUD_PROJECT]"
 ```
 
 **Required Parameters:**
@@ -102,7 +103,7 @@ Basic setup for your repository:
 For example:
 
 ```shell
-./scripts/setup_workload_identity.sh --repo google/my-repo --project my-project
+./scripts/setup_workload_identity.sh --repo "my-github-org/my-github-repo" --project "my-gcp-project"
 ```
 
 **Usage**
@@ -160,14 +161,15 @@ After running the `setup_workload_identity.sh` script, add the following variabl
 **Example**
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
     gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
     gcp_service_account: '${{ vars.SERVICE_ACCOUNT_EMAIL }}'
     gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
     gcp_location: '${{ vars.GOOGLE_CLOUD_LOCATION }}'
     use_vertex_ai: '${{ vars.GOOGLE_GENAI_USE_VERTEXAI }}'
-    prompt: 'Explain this code'
+    prompt: |-
+      Explain this code
 ```
 
 #### Connecting to Gemini Code Assist
@@ -193,14 +195,15 @@ After running the `setup_workload_identity.sh` script, add the following variabl
 **Example**
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
     gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
     gcp_service_account: '${{ vars.SERVICE_ACCOUNT_EMAIL }}'
     gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
     gcp_location: '${{ vars.GOOGLE_CLOUD_LOCATION }}'
     use_gemini_code_assist: '${{ vars.GOOGLE_GENAI_USE_GCA }}'
-    prompt: 'Explain this code'
+    prompt: |-
+      Explain this code
 ```
 
 ## GitHub Authentication
@@ -218,10 +221,10 @@ If the `APP_ID` and `APP_PRIVATE_KEY` secrets are not configured in your reposit
 *   **Limited Permissions:** The `GITHUB_TOKEN` has a restricted set of permissions. You may need to grant additional permissions directly within your workflow file to enable specific functionalities, such as:
 
 ```yaml
-permissions:                                                                                 
-    contents: read                                                                             
-    issues: write                                                                              
-    pull-requests: write
+permissions:
+  contents: 'read'
+  issues: 'write'
+  pull-requests: 'write'
 ```
 
 *   **Job-Scoped:** The token's access is limited to the repository where the workflow is running and expires when the job is complete.
@@ -244,7 +247,7 @@ For optimal security and control, we strongly recommend creating a custom GitHub
     > **Note:** Always adhere to the principle of least privilege. If your custom workflows require fewer permissions, adjust these settings accordingly.
 5.  Click **Create GitHub App**.
 
-A manifest is also available at `custom_app_manifest.yml`. For details on registering a GitHub App from a manifest, see the [GitHub documentation](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
+An example manifest is also available at [`examples/github-app/custom_app_manifest.yml`](../examples/github-app/custom_app_manifest.yml). For details on registering a GitHub App from a manifest, see the [GitHub documentation](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
 
 #### Step 2: Generate a Private Key and Get the App ID
 

docs/observability.md

@@ -19,7 +19,7 @@ The action uses its own built-in telemetry system that ensures consistent and re
 
 The Gemini CLI Action integrates OpenTelemetry to provide comprehensive observability for your workflows. This includes:
 
-- **Metrics**: Monitor performance indicators and usage statistics  
+- **Metrics**: Monitor performance indicators and usage statistics
 - **Logs**: Capture detailed information for debugging and analysis
 - **Traces**: Track the execution flow and timing of operations
 
@@ -30,7 +30,7 @@ Before enabling observability, ensure you have:
 - A Google Cloud project with billing enabled
 - Completed authentication setup (see [Authentication documentation](./authentication.md))
 - The following APIs enabled in your GCP project:
-  - Cloud Monitoring API  
+  - Cloud Monitoring API
   - Cloud Logging API
   - Cloud Trace API
 
@@ -49,13 +49,13 @@ environment.
 After running the setup script, configure your GitHub Actions workflow with the provided values:
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
-    gcp_workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
-    gcp_project_id: ${{ vars.GOOGLE_CLOUD_PROJECT }}
-    gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
+    gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
+    gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
+    gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
     # Enable telemetry in settings
-    settings: |
+    settings: |-
       {
         "telemetry": {
           "enabled": true,
@@ -86,29 +86,30 @@ The action automatically handles the setup of the OpenTelemetry (OTel) collector
 ```yaml
 jobs:
   review:
-    runs-on: ubuntu-latest
+    runs-on: 'ubuntu-latest'
     steps:
-      - uses: google-github-actions/run-gemini-cli@main
+      - uses: 'google-github-actions/run-gemini-cli@v0'
         with:
-          gcp_workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
-          gcp_service_account: ${{ vars.SERVICE_ACCOUNT_EMAIL }}
-          gcp_project_id: ${{ vars.GOOGLE_CLOUD_PROJECT }}
-          settings: |
+          gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
+          gcp_service_account: '${{ vars.SERVICE_ACCOUNT_EMAIL }}'
+          gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
+          settings: |-
             {
               "telemetry": {
                 "enabled": true,
                 "target": "gcp"
               }
             }
-          prompt: "Review this pull request"
+          prompt: |-
+            Review this pull request
 ```
 
 ## Disabling
 
 If you prefer to disable OpenTelemetry, you can explicitly opt out by setting `enabled: false` in your settings:
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
     gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
     gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
@@ -127,7 +128,7 @@ If you prefer to disable OpenTelemetry, you can explicitly opt out by setting `e
 Alternatively, you can omit the `telemetry` settings entirely, as telemetry is disabled by default:
 
 ```yaml
-- uses: google-github-actions/run-gemini-cli@main
+- uses: 'google-github-actions/run-gemini-cli@v0'
   with:
     gcp_workload_identity_provider: '${{ vars.GCP_WIF_PROVIDER }}'
     gcp_project_id: '${{ vars.GOOGLE_CLOUD_PROJECT }}'
@@ -149,7 +150,7 @@ Alternatively, you can omit the `telemetry` settings entirely, as telemetry is d
 **Permission errors:**
 - Verify your service account has these roles:
   - `roles/logging.logWriter`
-  - `roles/monitoring.editor` 
+  - `roles/monitoring.editor`
   - `roles/cloudtrace.agent`
 
 For additional troubleshooting guidance, see the [Authentication documentation](./authentication.md).

custom_app_manifest.yaml renamed to examples/github-app/custom_app_manifest.yml

@@ -23,7 +23,7 @@ This directory contains a collection of example workflows that demonstrate how t
 
 ## Setup
 
-For detailed setup instructions, including prerequisites and authentication, please refer to the main [Authentication documentation](../docs/authentication.md).
+For detailed setup instructions, including prerequisites and authentication, please refer to the main [Authentication documentation](../../docs/authentication.md).
 
 To use a workflow, you can utilize either of the following steps:
 - Run the `/setup-github` command in Gemini CLI on your terminal to set up workflows for your repository.
@@ -57,7 +57,7 @@ Add the following to your workflow YAML file to set a custom value:
 
 ```yaml
 with:
-  settings: |
+  settings: |-
     {
       "maxSessionTurns": 10
     }