best-practices.md

Best Practices

This guide provides best practices for using the Gemini CLI GitHub Action, with a focus on repository security and operational excellence.

• Best Practices
  • Repository Security
    • Branch and Tag Protection
    • Restrict PR Approvers
  • Workflow Configuration
    • Use Workload Identity Federation
    • Use Secrets for Sensitive Data
    • Pin Action Versions
  • Creating Custom Workflows
  • Monitoring and Auditing

Repository Security

A secure repository is the foundation for any reliable and safe automation. We strongly recommend implementing the following security measures.

Branch and Tag Protection

Protecting your branches and tags is critical to preventing unauthorized changes. You can use repository rulesets to configure protection for your branches and tags.

We recommend the following at a minimum for your main branch:

• Require a pull request before merging
• Require a minimum number of approvals
• Dismiss stale approvals
• Require status checks to pass before merging

For more information, see the GitHub documentation on managing branch protections.

Restrict PR Approvers

To prevent fraudulent or accidental approvals, you can restrict who can approve pull requests.

• CODEOWNERS: Use a CODEOWNERS file to define individuals or teams that are responsible for code in your repository.
• Code review limits: Limit code review approvals to specific users or teams.

Workflow Configuration

Use Workload Identity Federation

For the most secure authentication to Google Cloud, we recommend using Workload Identity Federation. This keyless authentication method eliminates the need to manage long-lived service account keys.

For detailed instructions on how to set up Workload Identity Federation, please refer to our Authentication documentation.

Use Secrets for Sensitive Data

Never hardcode secrets (e.g., API keys, tokens) in your workflows. Use GitHub Secrets to store sensitive information.

Pin Action Versions

To ensure the stability and security of your workflows, pin the Gemini CLI action to a specific version.

uses: google-github-actions/run-gemini-cli@v0

Creating Custom Workflows

When creating your own workflows, we recommend starting with the examples provided in this repository. These examples demonstrate how to use the run-gemini-cli action for various use cases, such as pull request reviews, issue triage, and more.

Ensure the new workflows you create follow the principle of least privilege. Only grant the permissions necessary to perform the required tasks.

Monitoring and Auditing

To gain deeper insights into the performance and behavior of Gemini CLI, you can enable OpenTelemetry to send traces, metrics, and logs to your Google Cloud project. This is highly recommended for production environments to monitor for unexpected behavior and performance issues.

For detailed instructions on how to set up and configure observability, please refer to our Observability documentation.