Automation and triage processes

This document provides a detailed overview of the automated processes we use to manage and triage issues and pull requests. Our goal is to provide prompt feedback and ensure that contributions are reviewed and integrated efficiently. Understanding this automation will help you as a contributor know what to expect and how to best interact with our repository bots.

Guiding principle: Issues and pull requests

First and foremost, almost every Pull Request (PR) should be linked to a corresponding Issue. The issue describes the "what" and the "why" (the bug or feature), while the PR is the "how" (the implementation). This separation helps us track work, prioritize features, and maintain clear historical context. Our automation is built around this principle.

<!-- prettier-ignore -->

[!NOTE] Issues tagged as "🔒Maintainers only" are reserved for project maintainers. We will not accept pull requests related to these issues.

---

Detailed automation workflows

Here is a breakdown of the specific automation workflows that run in our repository.

1. When you open an issue: Automated Issue Triage

This is the first bot you will interact with when you create an issue. Its job is to perform an initial analysis and apply the correct labels.

• Workflow File: .github/workflows/gemini-automated-issue-triage.yml
• When it runs: Immediately after an issue is created or reopened.
• What it does:
  • It uses a Gemini model to analyze the issue's title and body against a detailed set of guidelines.
  • Applies one area/* label: Categorizes the issue into a functional area of the project (for example, area/ux, area/models, area/platform).
  • Applies one kind/* label: Identifies the type of issue (for example, kind/bug, kind/enhancement, kind/question).
  • Applies one priority/* label: Assigns a priority from P0 (critical) to P3 (low) based on the described impact.
  • May apply status/need-information: If the issue lacks critical details (like logs or reproduction steps), it will be flagged for more information.
  • May apply status/need-retesting: If the issue references a CLI version that is more than six versions old, it will be flagged for retesting on a current version.
• What you should do:
  • Fill out the issue template as completely as possible. The more detail you provide, the more accurate the triage will be.
  • If the status/need-information label is added, provide the requested details in a comment.

2. When you open a pull request: Continuous Integration (CI)

This workflow ensures that all changes meet our quality standards before they can be merged.

• Workflow File: .github/workflows/ci.yml
• When it runs: On every push to a pull request.
• What it does:
  • Lint: Checks that your code adheres to our project's formatting and style rules.
  • Test: Runs our full suite of automated tests across macOS, Windows, and Linux, and on multiple Node.js versions. This is the most time-consuming part of the CI process.
  • Post Coverage Comment: After all tests have successfully passed, a bot will post a comment on your PR. This comment provides a summary of how well your changes are covered by tests.
• What you should do:
  • Ensure all CI checks pass. A green checkmark ✅ will appear next to your commit when everything is successful.
  • If a check fails (a red "X" ❌), click the "Details" link next to the failed check to view the logs, identify the problem, and push a fix.

3. Ongoing triage for pull requests: PR Auditing and Label Sync

This workflow runs periodically to ensure all open PRs are correctly linked to issues and have consistent labels.

• Workflow File: .github/workflows/gemini-scheduled-pr-triage.yml
• When it runs: Every 15 minutes on all open pull requests.
• What it does:
  • Checks for a linked issue: The bot scans your PR description for a keyword that links it to an issue (for example, Fixes #123, Closes #456).
  • Adds status/need-issue: If no linked issue is found, the bot will add the status/need-issue label to your PR. This is a clear signal that an issue needs to be created and linked.
  • Synchronizes labels: If an issue is linked, the bot ensures the PR's labels perfectly match the issue's labels. It will add any missing labels and remove any that don't belong, and it will remove the status/need-issue label if it was present.
• What you should do:
  • Always link your PR to an issue. This is the most important step. Add a line like Resolves #<issue-number> to your PR description.
  • This will ensure your PR is correctly categorized and moves through the review process smoothly.

4. Ongoing triage for issues: Scheduled Issue Triage

This is a fallback workflow to ensure that no issue gets missed by the triage process.

• Workflow File: .github/workflows/gemini-scheduled-issue-triage.yml
• When it runs: Every hour on all open issues.
• What it does:
  • It actively seeks out issues that either have no labels at all or still have the status/need-triage label.
  • It then triggers the same powerful Gemini-based analysis as the initial triage bot to apply the correct labels.
• What you should do:
  • You typically don't need to do anything. This workflow is a safety net to ensure every issue is eventually categorized, even if the initial triage fails.

5. Automatic unassignment of inactive contributors: Unassign Inactive Issue Assignees

To keep the list of open help wanted issues accessible to all contributors, this workflow automatically removes external contributors who have not opened a linked pull request within 7 days of being assigned. Maintainers, org members, and repo collaborators with write access or above are always exempt and will never be auto-unassigned.

• Workflow File: .github/workflows/unassign-inactive-assignees.yml
• When it runs: Every day at 09:00 UTC, and can be triggered manually with an optional dry_run mode.
• What it does:
  1. Finds every open issue labeled help wanted that has at least one assignee.
  2. Identifies privileged users (team members, repo collaborators with write+ access, maintainers) and skips them entirely.
  3. For each remaining (external) assignee it reads the issue's timeline to determine:
     • The exact date they were assigned (using assigned timeline events).
     • Whether they have opened a PR that is already linked/cross-referenced to the issue.
  4. Each cross-referenced PR is fetched to verify it is ready for review: open and non-draft, or already merged. Draft PRs do not count.
  5. If an assignee has been assigned for more than 7 days and no qualifying PR is found, they are automatically unassigned and a comment is posted explaining the reason and how to re-claim the issue.
  6. Assignees who have a non-draft, open or merged PR linked to the issue are never unassigned by this workflow.
• What you should do:
  • Open a real PR, not a draft: Within 7 days of being assigned, open a PR that is ready for review and include Fixes #<issue-number> in the description. Draft PRs do not satisfy the requirement and will not prevent auto-unassignment.
  • Re-assign if unassigned by mistake: Comment /assign on the issue to assign yourself again.
  • Unassign yourself if you can no longer work on the issue by commenting /unassign, so other contributors can pick it up right away.

6. Release automation

This workflow handles the process of packaging and publishing new versions of Gemini CLI.

• Workflow File: .github/workflows/release-manual.yml
• When it runs: On a daily schedule for "nightly" releases, and manually for official patch/minor releases.
• What it does:
  • Automatically builds the project, bumps the version numbers, and publishes the packages to npm.
  • Creates a corresponding release on GitHub with generated release notes.
• What you should do:
  • As a contributor, you don't need to do anything for this process. You can be confident that once your PR is merged into the main branch, your changes will be included in the very next nightly release.

We hope this detailed overview is helpful. If you have any questions about our automation or processes, don't hesitate to ask!