Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 23 additions & 18 deletions docs/trust-guidance.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,43 +31,48 @@ If you are processing **untrusted data**, you must strictly limit which tools th

### Allow List Configuration Examples

These examples demonstrate how to configure the tool allow list using the `settings_json` input in your GHA workflow.
These examples demonstrate how to configure the tool allow list using the `settings` input in your GHA workflow.

**Example A: Strict Allow List (Recommended for Untrusted Data)**

This configuration allows only the core native tools necessary for reading and searching files.

```
with:
settings_json: |
settings: |
{
"coreTools": [
"read_file",
"grep_search"
],
"sandbox": false
"tools": {
"core": [
"list_directory",
"read_file",
"grep_search"
]
}
}
```

| Tool Category | Tool/Command | Rationale |
| :--------------: | :-----------: | :------------------------------------------: |
| **Native Tools** | `read_file` | Recommended tool for reading content. |
| **Native Tools** | `grep_search` | Recommended tool for file pattern searching. |
| Tool Category | Tool/Command | Rationale |
| :--------------: | :--------------: | :------------------------------------------: |
| **Native Tools** | `list_directory` | Recommended tool for listing content. |
| **Native Tools** | `read_file` | Recommended tool for reading content. |
| **Native Tools** | `grep_search` | Recommended tool for file pattern searching. |

**Example B: Including Minimal Shell Commands (If Necessary)**

If your workflow requires a very simple shell command that cannot be replaced by a native tool, you can add it using `run_shell_command()`.

```
with:
settings_json: |
settings: |
{
"coreTools": [
"read_file",
"grep_search",
"run_shell_command(echo)"
],
"sandbox": false
"tools": {
"core": [
"list_directory",
"read_file",
"grep_search",
"run_shell_command(echo)"
]
}
}
```

Expand Down
5 changes: 3 additions & 2 deletions examples/workflows/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,10 @@ with:
{
"tools": {
"core": [
"list_directory",
"read_file",
"run_shell_command(echo)",
Comment thread
ehedlund marked this conversation as resolved.
"run_shell_command(gh label list)"
"grep_search",
"run_shell_command(echo)"
]
}
}
Expand Down
10 changes: 5 additions & 5 deletions examples/workflows/gemini-assistant/gemini-invoke.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ jobs:
TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
DESCRIPTION: '${{ github.event.pull_request.body || github.event.issue.body }}'
EVENT_NAME: '${{ github.event_name }}'
GEMINI_TRUST_WORKSPACE: 'true'
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
IS_PULL_REQUEST: '${{ !!github.event.pull_request }}'
ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
Expand Down Expand Up @@ -111,11 +112,10 @@ jobs:
},
"tools": {
"core": [
"run_shell_command(cat)",
"run_shell_command(echo)",
"run_shell_command(grep)",
"run_shell_command(head)",
"run_shell_command(tail)"
"list_directory",
"read_file",
"grep_search",
Comment thread
ehedlund marked this conversation as resolved.
Outdated
"run_shell_command(echo)"
Comment thread
ehedlund marked this conversation as resolved.
Outdated
]
}
}
Expand Down
10 changes: 5 additions & 5 deletions examples/workflows/gemini-assistant/gemini-plan-execute.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ jobs:
TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
DESCRIPTION: '${{ github.event.pull_request.body || github.event.issue.body }}'
EVENT_NAME: '${{ github.event_name }}'
GEMINI_TRUST_WORKSPACE: 'true'
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
IS_PULL_REQUEST: '${{ !!github.event.pull_request }}'
ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
Expand Down Expand Up @@ -119,11 +120,10 @@ jobs:
},
"tools": {
"core": [
"run_shell_command(cat)",
"run_shell_command(echo)",
"run_shell_command(grep)",
"run_shell_command(head)",
"run_shell_command(tail)"
"list_directory",
"read_file",
"grep_search",
"run_shell_command(echo)"
]
}
}
Expand Down
20 changes: 4 additions & 16 deletions examples/workflows/issue-triage/gemini-scheduled-triage.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ You are a highly efficient and precise Issue Triage Engineer. Your function is t

## Primary Directive

You will retrieve issue data and available labels from environment variables, analyze the issues, and assign the most relevant labels. You will then generate a single JSON array containing your triage decisions and write it to `!{echo $GITHUB_ENV}`.
You will retrieve issue data and available labels from environment variables, analyze the issues, and assign the most relevant labels. You will then generate a single JSON array containing your triage decisions.

## Critical Constraints

Expand All @@ -16,11 +16,7 @@ These are non-negotiable operational rules. Failure to comply will result in tas

2. **Label Exclusivity:** You **MUST** only use these labels: `!{echo $AVAILABLE_LABELS}`. You are strictly forbidden from inventing, altering, or assuming the existence of any other labels.

3. **Strict JSON Output:** The final output **MUST** be a single, syntactically correct JSON array. No other text, explanation, markdown formatting, or conversational filler is permitted in the final output file.

4. **Variable Handling:** Reference all shell variables as `"${VAR}"` (with quotes and braces) to prevent word splitting and globbing issues.

5. **Command Substitution**: When generating shell commands, you **MUST NOT** use command substitution with `$(...)`, `<(...)`, or `>(...)`. This is a security measure to prevent unintended command execution.
3. **Strict JSON Output:** The final output **MUST** be a single, syntactically correct JSON array. No other text, explanation, markdown formatting, or conversational filler is permitted.

## Input Data

Expand All @@ -36,11 +32,6 @@ The following data is provided for your analysis:
!{echo $ISSUES_TO_TRIAGE}
```

**Output File Path** where your final JSON output must be written:
```
!{echo $GITHUB_ENV}
```

## Execution Workflow

Follow this five-step process sequentially:
Expand All @@ -50,7 +41,6 @@ Follow this five-step process sequentially:
Parse the provided data above:
- Split the available labels by comma to get the list of valid labels.
- Parse the JSON array of issues to analyze.
- Note the output file path where you will write your results.

### Step 2: Analyze Label Semantics

Expand Down Expand Up @@ -85,13 +75,11 @@ Iterate through each issue object. For each issue:

### Step 5: Construct and Write Output

Assemble the results into a single JSON array, formatted as a string, according to the **Output Specification** below. Finally, execute the command to write this string to the output file, ensuring the JSON is enclosed in single quotes to prevent shell interpretation.

- Use the shell command to write: `echo 'TRIAGED_ISSUES=...' > "$GITHUB_ENV"` (Replace `...` with the final, minified JSON array string).
Assemble the results into a single JSON array, formatted as a string, according to the **Output Specification** below. Output the final JSON string directly.

## Output Specification

The output **MUST** be a JSON array of objects. Each object represents a triaged issue and **MUST** contain the following three keys:
The output **MUST** be ONLY a single, syntactically correct JSON array of objects. Do not include any other text, markdown formatting, or explanations. Each object represents a triaged issue and **MUST** contain the following three keys:

* `issue_number` (Integer): The issue's unique identifier.
* `labels_to_set` (Array of Strings): The list of labels to be applied.
Expand Down
7 changes: 3 additions & 4 deletions examples/workflows/issue-triage/gemini-scheduled-triage.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:
pull-requests: 'read'
outputs:
available_labels: '${{ steps.get_labels.outputs.available_labels }}'
triaged_issues: '${{ env.TRIAGED_ISSUES }}'
triaged_issues: '${{ steps.gemini_issue_analysis.outputs.summary }}'
steps:
- name: 'Get repository labels'
id: 'get_labels'
Expand Down Expand Up @@ -94,6 +94,7 @@ jobs:
${{ steps.find_issues.outputs.issues_to_triage != '[]' }}
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
env:
GEMINI_TRUST_WORKSPACE: 'true'
GITHUB_TOKEN: '' # Do not pass any auth token here since this runs on untrusted inputs
ISSUES_TO_TRIAGE: '${{ steps.find_issues.outputs.issues_to_triage }}'
REPOSITORY: '${{ github.repository }}'
Expand Down Expand Up @@ -127,9 +128,7 @@ jobs:
},
"tools": {
"core": [
"run_shell_command(echo)",
"run_shell_command(jq)",
"run_shell_command(printenv)"
"run_shell_command(echo)"
]
}
}
Expand Down
19 changes: 3 additions & 16 deletions examples/workflows/issue-triage/gemini-triage.toml
Original file line number Diff line number Diff line change
Expand Up @@ -27,28 +27,15 @@ You are an issue triage assistant. Analyze the current GitHub issue and identify
!{echo $ISSUE_BODY}
```

**Output File Path**:
```
!{echo $GITHUB_ENV}
```

## Steps

1. Review the issue title, issue body, and available labels provided above.

2. Based on the issue title and issue body, classify the issue and choose all appropriate labels from the list of available labels.

3. Convert the list of appropriate labels into a comma-separated list (CSV). If there are no appropriate labels, use the empty string.

4. Use the "echo" shell command to append the CSV labels to the output file path provided above:

```
echo "SELECTED_LABELS=[APPROPRIATE_LABELS_AS_CSV]" >> "[filepath_for_env]"
```
3. Output the appropriate labels as a comma-separated list (CSV).

for example:
## Output Specification

```
echo "SELECTED_LABELS=bug,enhancement" >> "/tmp/runner/env"
```
Output ONLY the comma-separated list of labels. Do not include any other text, markdown formatting, or explanations. If no labels apply, output an empty string.
"""
3 changes: 2 additions & 1 deletion examples/workflows/issue-triage/gemini-triage.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
timeout-minutes: 7
outputs:
available_labels: '${{ steps.get_labels.outputs.available_labels }}'
selected_labels: '${{ env.SELECTED_LABELS }}'
selected_labels: '${{ steps.gemini_analysis.outputs.summary }}'
permissions:
contents: 'read'
id-token: 'write'
Expand Down Expand Up @@ -61,6 +61,7 @@ jobs:
${{ steps.get_labels.outputs.available_labels != '' }}
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
env:
GEMINI_TRUST_WORKSPACE: 'true'
GITHUB_TOKEN: '' # Do NOT pass any auth tokens here since this runs on untrusted inputs
ISSUE_TITLE: '${{ github.event.issue.title }}'
ISSUE_BODY: '${{ github.event.issue.body }}'
Expand Down
10 changes: 5 additions & 5 deletions examples/workflows/pr-review/gemini-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ jobs:
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
id: 'gemini_pr_review'
env:
GEMINI_TRUST_WORKSPACE: 'true'
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
ISSUE_TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
ISSUE_BODY: '${{ github.event.pull_request.body || github.event.issue.body }}'
Expand Down Expand Up @@ -101,11 +102,10 @@ jobs:
},
"tools": {
"core": [
"run_shell_command(cat)",
"run_shell_command(echo)",
"run_shell_command(grep)",
"run_shell_command(head)",
"run_shell_command(tail)"
"list_directory",
"read_file",
"grep_search",
"run_shell_command(echo)"
]
}
}
Expand Down
Loading