Skip to content

Commit a84ad95

Browse files
ehedlundehedlund
committed
docs: modernize example workflows for trust and security
1 parent f77273f commit a84ad95

9 files changed

Lines changed: 63 additions & 77 deletions

File tree

‎docs/trust-guidance.md‎

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -31,43 +31,49 @@ If you are processing **untrusted data**, you must strictly limit which tools th
3131

3232
### Allow List Configuration Examples
3333

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

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

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

4040
```
4141
with:
42-
settings_json: |
42+
settings: |
4343
{
44-
"coreTools": [
45-
"read_file",
46-
"grep_search"
47-
],
48-
"sandbox": false
44+
"tools": {
45+
"core": [
46+
"list_directory",
47+
"read_file",
48+
"grep_search"
49+
],
50+
"sandbox": false
51+
}
4952
}
5053
```
5154

52-
| Tool Category | Tool/Command | Rationale |
53-
| :--------------: | :-----------: | :------------------------------------------: |
54-
| **Native Tools** | `read_file` | Recommended tool for reading content. |
55-
| **Native Tools** | `grep_search` | Recommended tool for file pattern searching. |
55+
| Tool Category | Tool/Command | Rationale |
56+
| :--------------: | :--------------: | :------------------------------------------: |
57+
| **Native Tools** | `list_directory` | Recommended tool for listing content. |
58+
| **Native Tools** | `read_file` | Recommended tool for reading content. |
59+
| **Native Tools** | `grep_search` | Recommended tool for file pattern searching. |
5660

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

5963
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()`.
6064

6165
```
6266
with:
63-
settings_json: |
67+
settings: |
6468
{
65-
"coreTools": [
66-
"read_file",
67-
"grep_search",
68-
"run_shell_command(echo)"
69-
],
70-
"sandbox": false
69+
"tools": {
70+
"core": [
71+
"list_directory",
72+
"read_file",
73+
"grep_search",
74+
"run_shell_command(echo)"
75+
]
76+
}
7177
}
7278
```
7379

‎examples/workflows/CONFIGURATION.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,9 +101,9 @@ with:
101101
{
102102
"tools": {
103103
"core": [
104+
"list_directory",
104105
"read_file",
105-
"run_shell_command(echo)",
106-
"run_shell_command(gh label list)"
106+
"grep_search"
107107
]
108108
}
109109
}

‎examples/workflows/gemini-assistant/gemini-invoke.yml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ jobs:
4747
TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
4848
DESCRIPTION: '${{ github.event.pull_request.body || github.event.issue.body }}'
4949
EVENT_NAME: '${{ github.event_name }}'
50+
GEMINI_TRUST_WORKSPACE: 'true'
5051
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
5152
IS_PULL_REQUEST: '${{ !!github.event.pull_request }}'
5253
ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
@@ -111,12 +112,12 @@ jobs:
111112
},
112113
"tools": {
113114
"core": [
114-
"run_shell_command(cat)",
115-
"run_shell_command(echo)",
116-
"run_shell_command(grep)",
117-
"run_shell_command(head)",
118-
"run_shell_command(tail)"
119-
]
115+
"list_directory",
116+
"read_file",
117+
"grep_search",
118+
"run_shell_command(echo)"
119+
],
120+
"sandbox": false
120121
}
121122
}
122123
prompt: '/gemini-invoke'

‎examples/workflows/gemini-assistant/gemini-plan-execute.yml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ jobs:
4949
TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
5050
DESCRIPTION: '${{ github.event.pull_request.body || github.event.issue.body }}'
5151
EVENT_NAME: '${{ github.event_name }}'
52+
GEMINI_TRUST_WORKSPACE: 'true'
5253
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
5354
IS_PULL_REQUEST: '${{ !!github.event.pull_request }}'
5455
ISSUE_NUMBER: '${{ github.event.pull_request.number || github.event.issue.number }}'
@@ -119,12 +120,12 @@ jobs:
119120
},
120121
"tools": {
121122
"core": [
122-
"run_shell_command(cat)",
123-
"run_shell_command(echo)",
124-
"run_shell_command(grep)",
125-
"run_shell_command(head)",
126-
"run_shell_command(tail)"
127-
]
123+
"list_directory",
124+
"read_file",
125+
"grep_search",
126+
"run_shell_command(echo)"
127+
],
128+
"sandbox": false
128129
}
129130
}
130131
prompt: '/gemini-plan-execute'

‎examples/workflows/issue-triage/gemini-scheduled-triage.toml‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ You are a highly efficient and precise Issue Triage Engineer. Your function is t
66
77
## Primary Directive
88
9-
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}`.
9+
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.
1010
1111
## Critical Constraints
1212
@@ -16,11 +16,7 @@ These are non-negotiable operational rules. Failure to comply will result in tas
1616
1717
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.
1818
19-
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.
20-
21-
4. **Variable Handling:** Reference all shell variables as `"${VAR}"` (with quotes and braces) to prevent word splitting and globbing issues.
22-
23-
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.
19+
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.
2420
2521
## Input Data
2622
@@ -36,11 +32,6 @@ The following data is provided for your analysis:
3632
!{echo $ISSUES_TO_TRIAGE}
3733
```
3834
39-
**Output File Path** where your final JSON output must be written:
40-
```
41-
!{echo $GITHUB_ENV}
42-
```
43-
4435
## Execution Workflow
4536
4637
Follow this five-step process sequentially:
@@ -50,7 +41,6 @@ Follow this five-step process sequentially:
5041
Parse the provided data above:
5142
- Split the available labels by comma to get the list of valid labels.
5243
- Parse the JSON array of issues to analyze.
53-
- Note the output file path where you will write your results.
5444
5545
### Step 2: Analyze Label Semantics
5646
@@ -85,13 +75,11 @@ Iterate through each issue object. For each issue:
8575
8676
### Step 5: Construct and Write Output
8777
88-
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.
89-
90-
- Use the shell command to write: `echo 'TRIAGED_ISSUES=...' > "$GITHUB_ENV"` (Replace `...` with the final, minified JSON array string).
78+
Assemble the results into a single JSON array, formatted as a string, according to the **Output Specification** below. Output the final JSON string directly.
9179
9280
## Output Specification
9381
94-
The output **MUST** be a JSON array of objects. Each object represents a triaged issue and **MUST** contain the following three keys:
82+
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:
9583
9684
* `issue_number` (Integer): The issue's unique identifier.
9785
* `labels_to_set` (Array of Strings): The list of labels to be applied.

‎examples/workflows/issue-triage/gemini-scheduled-triage.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jobs:
3636
pull-requests: 'read'
3737
outputs:
3838
available_labels: '${{ steps.get_labels.outputs.available_labels }}'
39-
triaged_issues: '${{ env.TRIAGED_ISSUES }}'
39+
triaged_issues: '${{ steps.gemini_issue_analysis.outputs.summary }}'
4040
steps:
4141
- name: 'Get repository labels'
4242
id: 'get_labels'
@@ -94,6 +94,7 @@ jobs:
9494
${{ steps.find_issues.outputs.issues_to_triage != '[]' }}
9595
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
9696
env:
97+
GEMINI_TRUST_WORKSPACE: 'true'
9798
GITHUB_TOKEN: '' # Do not pass any auth token here since this runs on untrusted inputs
9899
ISSUES_TO_TRIAGE: '${{ steps.find_issues.outputs.issues_to_triage }}'
99100
REPOSITORY: '${{ github.repository }}'
@@ -127,10 +128,9 @@ jobs:
127128
},
128129
"tools": {
129130
"core": [
130-
"run_shell_command(echo)",
131-
"run_shell_command(jq)",
132-
"run_shell_command(printenv)"
133-
]
131+
"run_shell_command(echo)"
132+
],
133+
"sandbox": false
134134
}
135135
}
136136
prompt: '/gemini-scheduled-triage'

‎examples/workflows/issue-triage/gemini-triage.toml‎

Lines changed: 3 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -27,28 +27,15 @@ You are an issue triage assistant. Analyze the current GitHub issue and identify
2727
!{echo $ISSUE_BODY}
2828
```
2929
30-
**Output File Path**:
31-
```
32-
!{echo $GITHUB_ENV}
33-
```
34-
3530
## Steps
3631
3732
1. Review the issue title, issue body, and available labels provided above.
3833
3934
2. Based on the issue title and issue body, classify the issue and choose all appropriate labels from the list of available labels.
4035
41-
3. Convert the list of appropriate labels into a comma-separated list (CSV). If there are no appropriate labels, use the empty string.
42-
43-
4. Use the "echo" shell command to append the CSV labels to the output file path provided above:
44-
45-
```
46-
echo "SELECTED_LABELS=[APPROPRIATE_LABELS_AS_CSV]" >> "[filepath_for_env]"
47-
```
36+
3. Output the appropriate labels as a comma-separated list (CSV).
4837
49-
for example:
38+
## Output Specification
5039
51-
```
52-
echo "SELECTED_LABELS=bug,enhancement" >> "/tmp/runner/env"
53-
```
40+
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.
5441
"""

‎examples/workflows/issue-triage/gemini-triage.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
timeout-minutes: 7
2323
outputs:
2424
available_labels: '${{ steps.get_labels.outputs.available_labels }}'
25-
selected_labels: '${{ env.SELECTED_LABELS }}'
25+
selected_labels: '${{ steps.gemini_analysis.outputs.summary }}'
2626
permissions:
2727
contents: 'read'
2828
id-token: 'write'
@@ -61,6 +61,7 @@ jobs:
6161
${{ steps.get_labels.outputs.available_labels != '' }}
6262
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
6363
env:
64+
GEMINI_TRUST_WORKSPACE: 'true'
6465
GITHUB_TOKEN: '' # Do NOT pass any auth tokens here since this runs on untrusted inputs
6566
ISSUE_TITLE: '${{ github.event.issue.title }}'
6667
ISSUE_BODY: '${{ github.event.issue.body }}'
@@ -94,7 +95,8 @@ jobs:
9495
"tools": {
9596
"core": [
9697
"run_shell_command(echo)"
97-
]
98+
],
99+
"sandbox": false
98100
}
99101
}
100102
prompt: '/gemini-triage'

‎examples/workflows/pr-review/gemini-review.yml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ jobs:
4545
uses: 'google-github-actions/run-gemini-cli@v0' # ratchet:exclude
4646
id: 'gemini_pr_review'
4747
env:
48+
GEMINI_TRUST_WORKSPACE: 'true'
4849
GITHUB_TOKEN: '${{ steps.mint_identity_token.outputs.token || secrets.GITHUB_TOKEN || github.token }}'
4950
ISSUE_TITLE: '${{ github.event.pull_request.title || github.event.issue.title }}'
5051
ISSUE_BODY: '${{ github.event.pull_request.body || github.event.issue.body }}'
@@ -101,12 +102,12 @@ jobs:
101102
},
102103
"tools": {
103104
"core": [
104-
"run_shell_command(cat)",
105-
"run_shell_command(echo)",
106-
"run_shell_command(grep)",
107-
"run_shell_command(head)",
108-
"run_shell_command(tail)"
109-
]
105+
"list_directory",
106+
"read_file",
107+
"grep_search",
108+
"run_shell_command(echo)"
109+
],
110+
"sandbox": false
110111
}
111112
}
112113
extensions: |

0 commit comments

Comments
 (0)