grafana/.github/bot.md

GitHub & grafanabot automation

The bot is configured via commands.json and some other GitHub workflows workflows.

Comment commands:

• Write the word /duplicate #<number> anywhere in a comment and the bot will add the correct label and standard message.
• Write the word /needsMoreInfo anywhere in a comment and the bot will add the correct label and standard message.

Label commands:

• Add label bot/question the bot will close with standard question message and add label type/question
• Add label bot/duplicate the bot will close with standard duplicate message and add label type/duplicate
• Add label bot/needs more info for bot to request more info (or use comment command mentioned above)
• Add label bot/close feature request for bot to close a feature request with standard message and adds label not implemented
• Add label bot/no new info for bot to close an issue where we asked for more info but has not received any updates in at least 14 days.

Metrics

Metrics are configured in metrics-collector.json and are also defined in the metrics-collector GitHub action.

Backport PR

To automatically backport a PR to a release branch like v7.3.x add a label named backport v7.3.x. The label name should follow the pattern backport <branch-name>. Once merged grafanabot will automatically try to cherry-pick the PR merge commit into that branch and open a PR. You must then add the milestone to your backport PR.

If there are merge conflicts the bot will write a comment on the source PR saying the cherry-pick failed. In this case you have to do the cherry pick and backport PR manually.

The backport logic is written here

Auto triager bot

The auto triager bot is a github action that assigns labels to issues based on the issue contents. The logic to assign labels is its own program and lives here. It uses an LLM to do this.

The bot runs every time a new issue is opened in the grafana/grafana repository. You can find the bot definition here

The job only assign labels when the issue author is not a member of the Grafana organization in GitHub. The bot concurrency is 1.

This bot is not responsible for assigning teams, the commands workflow is responsible for doing that

General diagram

sequenceDiagram
    actor User
    participant GH as GitHub
    participant AT as Auto Triager Job
    participant ATP as Auto Triager Program
    participant LLM as LLM Service
    participant CJ as Commands Job

    User->>GH: Opens Issue
    GH->>GH: Check if user in Grafana org
    alt User not in Grafana org
        GH->>AT: Trigger Auto Triager Job
        AT->>ATP: Execute program
        ATP->>LLM: Send issue content & categories
        LLM-->>ATP: Return matching categories
        ATP-->>GH: Assign labels to issue
        GH->>CJ: Trigger Commands Job
        CJ->>CJ: Read commands.json
        CJ-->>GH: Assign teams based on labels
    end

Team definitions

The team associated with labels are defined here. This bot is not responsible for assigning teams, the commands workflow is responsible for doing that.

The commands workflow code can be found here

Categories/Labels definitions

The categories (or labels) and the types used to categorize issues are defined in this same repository here the prompt that is passed to the LLM is also defined there.

If you are adding a new category in the auto-triager repository you must define a team that owns the label in the commands.json.

If you remove a label from the commands.json and it doesn't have any other team associated with it you must remove it from the labels file

Secrets

The bot secrets live in the vault. It uses a shared workflow to get the vault secrets, the workflow requires a token with contents:read and id-token:write scopes for it to work.

How to detect the bot is working?

The list of unlabeled issues should remain empty as long as the bot is running. There might be issues in the list if some team member removed all labels, but if the list grows to more than 5 it is likely the bot is not working correctly.

What to do if this bot is not working?

You can contact the plugins platform team in slack #grafana-plugins-platform and inform about the issue.

Troubleshooting

Possible reasons why the bot is not working:

• The OpenAI API key is not valid anymore. The action output will show this in its error log. A new key needs to be generated via the OpenAI UI and its value updated in vault. See the action to find the correct path to update the key.
• The Slack webhook URL is not valid anymore. The action output will show this in its error log or the #triage-automation-ci channel will stop showing messages about issue triaging. A new slack webhook url needs to be generated for the auto triager app and its value updated in vault.
• This bot is not responsible for assigning teams, the commands workflow is responsible for doing that