Use Gemini CLI Security Extension for GitHub PR reviews

1. Introduction

The Gemini CLI Security Extension is a Google-built open source Gemini CLI extension that analyzes code for security risks and vulnerabilities. You can use the Security extension with Gemini CLI to identify security issues locally, just as you would with any other Gemini CLI extension. You can also invoke it to review Pull Requests on GitHub. In this codelab, we will go over how to use the Security extension in your GitHub repository.

What you'll do

• Configure secure authentication from GitHub to Google Cloud
• Create a GitHub Actions workflow that calls on the Gemini CLI Security Extension
• Run a security review on a new or existing PR using GitHub Actions

What you'll learn

• How to use Workload Identity Federation for secure authentication from GitHub Actions to Google Cloud
• Learn the benefits of using a Workload Identity Pool and Workload Identity Provider over a Gemini API key for authentication
• How to run a security review with PRs
• How to interpret security reviews returned by the Security extension

What you'll need

• A web browser
• A GitHub account and repository
• A Google Cloud project

This codelab is designed for developers familiar with the CI/CD workflow on GitHub. You are not expected to have familiarity with Gemini CLI or Gemini CLI extensions. If you want to learn how extensions work, check out the codelab: Getting Started with Gemini CLI Extensions.

In this codelab, you will learn how to set up the Gemini CLI Security Extension in your GitHub repository. We won't suggest code for you to open a PR against your repository to trigger a security vulnerability finding.

2. Before you begin

For Google Cloud Credits: To help you get started, redeem your free Google Cloud credits. Follow the instructions to activate the credit and create a new project.

Create or select a project

1. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
2. Make sure that billing is enabled for your Cloud project. Learn how to verify billing.
3. Open Cloud Shell, a command-line environment running in Google Cloud. Click Activate Cloud Shell at the top of the Google Cloud console.

4. Once connected to Cloud Shell, check that you're authenticated and the project is set to your project ID using the following command:

gcloud auth list

5. Run the following command to confirm that the gcloud command is configured to use your project.

gcloud config list project

6. If your project is not set, use the following command to set it:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

3. Set up auth from GitHub to Google Cloud

How it works

Workload Identity Federation is the recommended way to authenticate from GitHub Actions to Google Cloud.

1. For every GitHub Actions workflow run job, GitHub as an external Identity Provider issues a signed JWT (JSON Web Token). This token contains "claims" such as repository, workflow, and job_workflow_ref, which act as a digital identity card for that specific runner. In this lab, you will create a GitHub Actions workflow with a job that uses the google-github-actions/run-gemini-cli action, which will request a JWT from GitHub and send this token to the Security Token Service (STS) in Google Cloud.
2. You will configure a Workload Identity Pool and a Provider in Google Cloud by setting the issuer URL to the official GitHub token service URL https://token.actions.githubusercontent.com and defining your "Attribute Mappings", which typically include repository and branch names. Google Cloud STS validates the JWT against the Workload Identity Pool rules. If everything, including the attribute mappings, checks out, the STS exchanges the GitHub token for a short-lived Google Cloud Federated Access Token.
3. Now the google-github-actions/run-gemini-cli action in your GitHub Actions workflow can use the short-lived Google Cloud Federated Access Token to "impersonate" a connected Service Account to the Workload Identity Pool. The connected Service Account needs to have the necessary IAM roles and permissions to access any Google Cloud resources and services.

   GitHub uses direct identity federation without service account impersonation. However, Gemini CLI requires a service account token creation, which is only supported via service account impersonation.

Benefits of using Workload Identity Federation over Gemini API Key

It is possible to authenticate Gemini CLI calls originated from GitHub Actions using a Gemini API Key, which involves creating a new GitHub Actions secret named GEMINI_API_KEY with the appropriate key value. However, this is discouraged for the following security reasons:

• Gemini API keys can have broad permissions from their respective IAM role bindings. When compromised, they open up access to a broad range of Google Cloud resources and services. Workload Identity Federation makes use of service accounts and short-lived access tokens, which tightens auth significantly.
• Gemini API keys are also challenging to manage at scale. Identifying which workflows are using an exposed key takes time. Rotating the keys manually also takes time. On the other hand, you can easily look up, edit, and delete Workload Identity pools and providers associated with your repository from the Cloud Console.
• With Gemini API keys, you have to always double-check that you aren't accidentally exposing them in any access or debug logs. With Workload Identity Federation, you don't store any GitHub Actions workflows secrets but variables, which are inherently less sensitive.

Configure GitHub Actions and Google Cloud

1. In your Cloud Shell, log into your GitHub account.

gh auth login

2. Create a new file setup_workload_identity.sh and copy and paste the setup script from the google-github-actions/run-gemini-cli repository.
3. Make the script into an executable.

chmod +x setup_workload_identity.sh

4. Run the script.

./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}

4. Create a GitHub Actions workflow

1. Check out a GitHub repository that you own.

git clone {YOUR_REPO}
cd {YOUR REPO}

2. Create a GitHub Actions workflow that calls on the slash command /security:analyze-github-pr by copying an example workflow yml script from the /gemini-cli-extensions/security repo.

git checkout -b workflow
mkdir .github/ && cd .github/
mkdir workflows/ && cd workflows/
curl -L https://raw.githubusercontent.com/gemini-cli-extensions/security/refs/heads/main/.github/workflows/gemini-review.yml -o gemini-review.yml

3. Push the GitHub Actions workflow to your remote origin on GitHub.

git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow

5. Run security analysis workflow on new and existing PRs

Start a new PR in your GitHub repository or post a new comment "@gemini-cli /review" as a repo owner or contributor. This will start a security review on the PR. The Gemini CLI Security Extension from the GitHub Actions workflow that you have committed to your repo will tag any security issues it finds by severity categories from "Critical", "High", "Medium", to "Low".

Here is an example of a security review on a new PR and an example of a security review on an existing PR.

6. Further exploration

We encourage you to explore a growing list of custom commands featuring new security capabilities in the Gemini CLI Security extension and start using it in your workflows. For example:

• /security:scan-deps cross-references your project's dependencies with OSV.dev.

Check out the release notes for the latest features and bug fixes too.

7. Congratulations

Congratulations, you've successfully configured your GitHub repository to use the Gemini CLI Security Extension to analyze PRs for security risks and vulnerabilities.