Observability Onboarding Improvements (#81)

### Description
Addresses a few potential issues in the observability onboarding process

### Changes

- Clarify that `gcloud` is a prerequisite 
- Explicitly pass `project_id`, since the automatic discovery was
causing the tool to exit early in a way that didn't communicate the
error to the user
- Handle when the `pool` is in a `DELETED` state (by
[undeleting](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/providers/undelete)
it)
- Handle when the `provider` is in a `DELETED` state (by
[undeleting](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/undelete)
it)

### Testing 
Tested a missing `project_id` input:
```
leehagoodjames@mac  ➜  run-gemini-cli git:(observability-docs) ./scripts/setup_workload_identity.sh --repo google-gemini/logo-maker
❌ GCP project is required. Use --project PROJECT_ID

💡 To find your project name:
   1. Go to your GCP console
   2. The URL shows: https://pantheon.corp.google.com/welcome?project=PROJECT_ID

Use --help for usage information.
```

Tested with the logo-maker project, which updated the `pool` and
`provider` from a `DELETED` status to `ACTIVE`

---------

Signed-off-by: Lee James <40045512+leehagoodjames@users.noreply.github.com>
Co-authored-by: 8bitmp3 <19637339+8bitmp3@users.noreply.github.com>

Author: leehagoodjames

docs/observability.md

@@ -31,15 +31,18 @@ For detailed setup instructions, see the [Workload Identity Federation documenta
 
 ### Quick Setup
 
-Run the following command from the root of this repository:
+> Note that setting up this Observability requires a Google Cloud account as well as Google Cloud CLI (install gcloud [here](https://cloud.google.com/sdk/docs/install))
 
 ```bash
-./scripts/setup_workload_identity.sh --repo <OWNER/REPO>
+./scripts/setup_workload_identity.sh --repo <OWNER/REPO> --project <PROJECT_ID>
 ```
 
 -   `<OWNER/REPO>`: Your GitHub repository in the format `owner/repo`.
+-   `<PROJECT_ID>`: Your Google Cloud `project_id`.
 
-After the script completes, it will output the values for the inputs listed above. You must add these to your GitHub repository's variables (and GEMINI_API_KEY as a secret) to complete the setup.
+After the `setup_workload_identity.sh` script finishes running, it will output a link to where you can edit your repository variables. Click on that link and then add the variables output from the script into your GitHub "Repository variables".
+
+Additionally, to complete the setup add your `GEMINI_API_KEY` as a secret - this is discussed in more detail in the `run-gemini-cli` [README](https://github.com/google-github-actions/run-gemini-cli?tab=readme-ov-file#getting-started).
 
 ## Advanced Setup
 

scripts/setup_workload_identity.sh

@@ -66,9 +66,9 @@ USAGE:
 
 REQUIRED:
     -r, --repo OWNER/REPO       GitHub repository (e.g., google/my-repo)
+    -p, --project PROJECT_ID    Google Cloud project ID (auto-detected if not provided)
 
 OPTIONS:
-    -p, --project PROJECT_ID    Google Cloud project ID (auto-detected if not provided)
     --pool-name NAME           Custom workload identity pool name (default: auto-generated)
     -h, --help                 Show this help
 
@@ -135,6 +135,16 @@ if [[ -z "${GITHUB_REPO}" ]]; then
     echo "Use --help for usage information."
     exit 1
 fi
+if [[ -z "${GOOGLE_CLOUD_PROJECT}" ]]; then
+    print_error "GCP project is required. Use --project PROJECT_ID"
+    echo ""
+    echo "💡 To find your project name:"
+    echo "   1. Go to your Google Cloud console"
+    echo "   2. The URL displays: https://pantheon.corp.google.com/welcome?project=PROJECT_ID"
+    echo ""
+    echo "Use --help for usage information."
+    exit 1
+fi
 
 # Validate repository format
 if [[ ! "${GITHUB_REPO}" =~ ^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$ ]]; then
@@ -226,7 +236,30 @@ if ! gcloud iam workload-identity-pools describe "${POOL_NAME}" \
         --display-name="GitHub Actions Pool"
     print_success "Workload Identity Pool created"
 else
-    print_success "Workload Identity Pool already exists"
+    print_info "Workload Identity Pool '${POOL_NAME}' exists. Verifying state..."
+    # Fetch the current state of the existing pool.
+    POOL_STATE=$(gcloud iam workload-identity-pools describe "${POOL_NAME}" \
+        --project="${GOOGLE_CLOUD_PROJECT}" \
+        --location="${GOOGLE_CLOUD_LOCATION}" \
+        --format="value(state)")
+
+    if [[ "${POOL_STATE}" == "ACTIVE" ]]; then
+        # Pool exists and is in the correct state.
+        print_success "Workload Identity Pool already exists and is ACTIVE."
+    else
+        if [[ "${POOL_STATE}" == "DELETED" ]]; then
+        # Pool exists but is DELETED. Undelete the pool. 
+        print_warning "Workload Identity Pool already exists but is in a DELETED state. Running 'undelete'."
+        gcloud iam workload-identity-pools undelete "${POOL_NAME}" \
+            --project="${GOOGLE_CLOUD_PROJECT}" \
+            --location="${GOOGLE_CLOUD_LOCATION}"
+        else
+        # Pool exists but is in an unexpected state.
+        print_error "Pool '${POOL_NAME}' is in an unexpected state: '${POOL_STATE}'. Expected states are: {'ACTIVE', 'DELETED'}. Exiting"
+        exit 1
+
+        fi
+    fi
 fi
 
 # Get the pool ID
@@ -254,7 +287,32 @@ if ! gcloud iam workload-identity-pools providers describe "${PROVIDER_NAME}" \
         --issuer-uri="https://token.actions.githubusercontent.com"
     print_success "Workload Identity Provider created"
 else
-    print_success "Workload Identity Provider already exists"
+    print_info "Workload Identity Provider '${PROVIDER_NAME}' exists. Verifying state..."
+    # Fetch the current state of the existing provider.
+    PROVIDER_STATE=$(gcloud iam workload-identity-pools providers describe "${PROVIDER_NAME}" \
+        --project="${GOOGLE_CLOUD_PROJECT}" \
+        --location="${GOOGLE_CLOUD_LOCATION}" \
+        --workload-identity-pool="${POOL_NAME}" \
+        --format="value(state)")
+
+    if [[ "${PROVIDER_STATE}" == "ACTIVE" ]]; then
+        # Provider exists and is in the correct state.
+        print_success "Workload Identity Provider already exists and is ACTIVE."
+    else
+        if [[ "${PROVIDER_STATE}" == "DELETED" ]]; then
+        # Provider exists but is DELETED. Undelete the provider. 
+        print_warning "Workload Identity Provider already exists but is in a DELETED state. Running 'undelete'."
+        gcloud iam workload-identity-pools providers undelete "${PROVIDER_NAME}" \
+            --project="${GOOGLE_CLOUD_PROJECT}" \
+            --location="${GOOGLE_CLOUD_LOCATION}" \
+            --workload-identity-pool="${POOL_NAME}"
+        else
+        # Provider exists but is in an unexpected state.
+        print_error "Provider '${PROVIDER_NAME}' is in an unexpected state: '${PROVIDER_STATE}'. Expected states are: {'ACTIVE', 'DELETED'}. Exiting"
+        exit 1
+
+        fi
+    fi
 fi
 
 # Step 4: Grant required permissions to the Workload Identity Pool