feat: add best practices guide (#245)

This commit introduces a new guide on best practices that covers key
areas such as repository security, workflow configuration, and
monitoring.

The `README.md` file has been updated to include a new "Best Practices"
section that summarizes the key recommendations from the guide and links
to the full documentation.

Closes #97

Author: jerop

README.md

@@ -136,9 +136,7 @@ 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](./examples/workflows/pr-review).
 
-There is a [known issue](https://github.com/google-github-actions/run-gemini-cli/issues/169) that action bot may approve the PR occasionally,
-to avoid this situation as org owner you can restrict who can approve the PR following
-[Code Review Limits](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository#enabling-code-review-limits).
+
 
 ### Gemini CLI Assistant
 
@@ -268,6 +266,18 @@ for debugging and optimization.
 For detailed instructions on how to set up and configure observability, go to
 the [Observability documentation](./docs/observability.md).
 
+## Best Practices
+
+To ensure the security, reliability, and efficiency of your automated workflows, we strongly recommend following our best practices. These guidelines cover key areas such as repository security, workflow configuration, and monitoring.
+
+Key recommendations include:
+
+*   **Securing Your Repository:** Implementing branch and tag protection, and restricting pull request approvers.
+*   **Workflow Configuration:** Using Workload Identity Federation for secure authentication to Google Cloud, managing secrets effectively, and pinning action versions to prevent unexpected changes.
+*   **Monitoring and Auditing:** Regularly reviewing action logs and enabling OpenTelemetry for deeper insights into performance and behavior.
+
+For a comprehensive guide on securing your repository and workflows, please refer to our [**Best Practices documentation**](./docs/best-practices.md).
+
 ## Customization
 
 Create a [GEMINI.md] file in the root of your repository to provide

docs/best-practices.md

@@ -0,0 +1,77 @@
+# 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](#best-practices)
+  - [Repository Security](#repository-security)
+    - [Branch and Tag Protection](#branch-and-tag-protection)
+    - [Restrict PR Approvers](#restrict-pr-approvers)
+  - [Workflow Configuration](#workflow-configuration)
+    - [Use Workload Identity Federation](#use-workload-identity-federation)
+    - [Use Secrets for Sensitive Data](#use-secrets-for-sensitive-data)
+    - [Pin Action Versions](#pin-action-versions)
+  - [Creating Custom Workflows](#creating-custom-workflows)
+  - [Monitoring and Auditing](#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**](./authentication.md).
+
+### 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.
+
+```yaml
+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](../examples/workflows/). 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**](./observability.md).
+
+[repository rulesets]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets
+[managing branch protections]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
+[`codeowners` file]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+[limit code review approvals]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository#enabling-code-review-limits
+[github secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets
+[Workload Identity Federation]: https://cloud.google.com/iam/docs/workload-identity-federation