Skip to content

Commit 5944fcc

Browse files
Copilotpelikhan
Copilot
and
pelikhan
committed
Move environment variables documentation to specs folder
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
1 parent d18d192 commit 5944fcc

3 files changed

Lines changed: 298 additions & 290 deletions

File tree

‎docs/src/content/docs/reference/environment-variables.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ jobs:
232232
## Related Documentation
233233

234234
- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete frontmatter configuration
235-
- [Safe Outputs - Environment Variables Reference](/gh-aw/reference/safe-outputs/#environment-variables-reference) - Detailed environment variables for each safe output job type
235+
- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output environment configuration
236236
- [Sandbox](/gh-aw/reference/sandbox/) - Sandbox environment variables
237237
- [Tools](/gh-aw/reference/tools/) - MCP tool configuration
238238
- [Safe Inputs](/gh-aw/reference/safe-inputs/) - Safe input tool configuration

‎docs/src/content/docs/reference/safe-outputs.md‎

Lines changed: 0 additions & 289 deletions
Original file line numberDiff line numberDiff line change
@@ -971,295 +971,6 @@ footer: "> [View workflow source]({workflow_source_url})"
971971

972972
Custom messages can be imported from shared workflows. Local messages override imported ones.
973973

974-
## Environment Variables Reference
975-
976-
Safe output jobs use environment variables to pass configuration from workflow frontmatter to the generated GitHub Actions jobs. Understanding these variables helps with debugging and troubleshooting configuration issues.
977-
978-
### Common Environment Variables
979-
980-
These environment variables are present in all safe output jobs:
981-
982-
| Variable | Description | Required | Example |
983-
|----------|-------------|----------|---------|
984-
| `GH_AW_AGENT_OUTPUT` | Path to agent output file containing safe output requests | Yes | `/tmp/gh-aw/safeoutputs/outputs.jsonl` |
985-
| `GH_AW_WORKFLOW_NAME` | Workflow name for attribution in footers and messages | Yes | `"Issue Triage"` |
986-
| `GH_AW_WORKFLOW_SOURCE` | Source location in format `owner/repo/path@ref` | No | `"owner/repo/workflows/triage.md@main"` |
987-
| `GH_AW_WORKFLOW_SOURCE_URL` | GitHub URL to workflow source file | No | Auto-generated from source |
988-
| `GH_AW_TRACKER_ID` | Tracker ID for linking related workflows | No | `"issue-123"` |
989-
| `GH_AW_ENGINE_ID` | AI engine identifier (copilot, claude, codex, custom) | No | `"copilot"` |
990-
| `GH_AW_ENGINE_VERSION` | AI engine version | No | `"1.0.0"` |
991-
| `GH_AW_ENGINE_MODEL` | AI engine model name | No | `"gpt-4"` |
992-
| `GH_AW_SAFE_OUTPUTS_STAGED` | Preview mode flag - when true, operations are previewed but not executed | No | `"true"` |
993-
| `GH_AW_TARGET_REPO_SLUG` | Target repository for cross-repo operations | No | `"owner/target-repo"` |
994-
| `GH_AW_SAFE_OUTPUT_MESSAGES` | Custom message templates in JSON format | No | JSON string |
995-
| `GITHUB_TOKEN` | GitHub API authentication token | Yes | From secrets or default `GITHUB_TOKEN` |
996-
997-
### Job-Specific Environment Variables
998-
999-
Each safe output type has additional environment variables specific to its configuration:
1000-
1001-
#### Create Issue (`create-issue:`)
1002-
1003-
| Variable | Description | Set When | Example |
1004-
|----------|-------------|----------|---------|
1005-
| `GH_AW_ISSUE_TITLE_PREFIX` | Prefix for issue titles | `title-prefix` configured | `"[ai] "` |
1006-
| `GH_AW_ISSUE_LABELS` | Comma-separated labels to add | `labels` configured | `"automation,ai"` |
1007-
| `GH_AW_ISSUE_ALLOWED_LABELS` | Comma-separated allowed labels | `allowed-labels` configured | `"bug,enhancement"` |
1008-
| `GH_AW_ISSUE_EXPIRES` | Days until auto-close | `expires` configured | `"7"` |
1009-
| `GH_AW_ASSIGN_COPILOT` | Assign copilot agent to created issues | `assignees: copilot` configured | `"true"` |
1010-
| `GH_AW_TEMPORARY_ID_MAP` | Map of temporary IDs to real issue numbers | Multiple issues with references | From previous job output |
1011-
1012-
#### Create Pull Request (`create-pull-request:`)
1013-
1014-
| Variable | Description | Set When | Example |
1015-
|----------|-------------|----------|---------|
1016-
| `GH_AW_WORKFLOW_ID` | Workflow identifier for branch naming | Always | `"agent"` (job name) |
1017-
| `GH_AW_BASE_BRANCH` | Base branch for PR | Always | `${{ github.ref_name }}` |
1018-
| `GH_AW_PR_TITLE_PREFIX` | Prefix for PR titles | `title-prefix` configured | `"[agent] "` |
1019-
| `GH_AW_PR_LABELS` | Comma-separated labels to add | `labels` configured | `"automation"` |
1020-
| `GH_AW_PR_ALLOWED_LABELS` | Comma-separated allowed labels | `allowed-labels` configured | `"automation,bug"` |
1021-
| `GH_AW_PR_DRAFT` | Create as draft PR | Always (default: `true`) | `"true"` or `"false"` |
1022-
| `GH_AW_PR_IF_NO_CHANGES` | Behavior when no changes detected | Always (default: `warn`) | `"warn"`, `"error"`, or `"ignore"` |
1023-
| `GH_AW_PR_ALLOW_EMPTY` | Allow PRs with no changes | Always (default: `false`) | `"true"` or `"false"` |
1024-
| `GH_AW_MAX_PATCH_SIZE` | Maximum patch size in KB | Always (default: `1024`) | `1024` |
1025-
| `GH_AW_PR_EXPIRES` | Days until auto-close (same-repo only) | `expires` configured | `"14"` |
1026-
| `GH_AW_COMMENT_ID` | Comment ID from activation job | Command-triggered workflow | From activation job output |
1027-
| `GH_AW_COMMENT_REPO` | Repository containing comment | Command-triggered workflow | From activation job output |
1028-
1029-
#### Add Comment (`add-comment:`)
1030-
1031-
| Variable | Description | Set When | Example |
1032-
|----------|-------------|----------|---------|
1033-
| `GH_AW_COMMENT_TARGET` | Target for comments: `triggering`, `*`, or number | `target` configured | `"*"` or `"123"` |
1034-
| `GH_AW_HIDE_OLDER_COMMENTS` | Hide older comments from same workflow | `hide-older-comments: true` | `"true"` |
1035-
| `GH_AW_ALLOWED_REASONS` | Allowed hide reasons as JSON array | `allowed-reasons` configured | `["outdated","resolved"]` |
1036-
| `GH_AW_CREATED_ISSUE_URL` | URL of created issue | Depends on `create-issue` job | From create-issue job output |
1037-
| `GH_AW_CREATED_ISSUE_NUMBER` | Number of created issue | Depends on `create-issue` job | From create-issue job output |
1038-
| `GH_AW_CREATED_DISCUSSION_URL` | URL of created discussion | Depends on `create-discussion` job | From create-discussion job output |
1039-
| `GH_AW_CREATED_DISCUSSION_NUMBER` | Number of created discussion | Depends on `create-discussion` job | From create-discussion job output |
1040-
| `GH_AW_CREATED_PULL_REQUEST_URL` | URL of created PR | Depends on `create-pull-request` job | From create-pull-request job output |
1041-
| `GH_AW_CREATED_PULL_REQUEST_NUMBER` | Number of created PR | Depends on `create-pull-request` job | From create-pull-request job output |
1042-
| `GH_AW_TEMPORARY_ID_MAP` | Map of temporary IDs to real numbers | Issues with temporary IDs created | From create-issue job output |
1043-
1044-
#### Create Discussion (`create-discussion:`)
1045-
1046-
| Variable | Description | Set When | Example |
1047-
|----------|-------------|----------|---------|
1048-
| `GH_AW_DISCUSSION_TITLE_PREFIX` | Prefix for discussion titles | `title-prefix` configured | `"[ai] "` |
1049-
| `GH_AW_DISCUSSION_CATEGORY` | Category slug, name, or ID | `category` configured | `"general"` or `"DIC_kwDOABCD123"` |
1050-
| `GH_AW_CLOSE_OLDER_DISCUSSIONS` | Close older discussions from same workflow | Multiple discussions with closing | `"true"` |
1051-
| `GH_AW_DISCUSSION_EXPIRES` | Days until auto-close | `expires` configured | `"3"` |
1052-
| `GH_AW_TEMPORARY_ID_MAP` | Map of temporary IDs to real issue numbers | Issues created with references | From create-issue job output |
1053-
1054-
#### Close Issue (`close-issue:`)
1055-
1056-
| Variable | Description | Set When | Example |
1057-
|----------|-------------|----------|---------|
1058-
| `GH_AW_ISSUE_REQUIRED_LABELS` | Required labels (any match) | `required-labels` configured | `"automated,bot"` |
1059-
| `GH_AW_ISSUE_REQUIRED_TITLE_PREFIX` | Required title prefix | `required-title-prefix` configured | `"[bot]"` |
1060-
1061-
#### Close Pull Request (`close-pull-request:`)
1062-
1063-
| Variable | Description | Set When | Example |
1064-
|----------|-------------|----------|---------|
1065-
| `GH_AW_PR_REQUIRED_LABELS` | Required labels (any match) | `required-labels` configured | `"automated,stale"` |
1066-
| `GH_AW_PR_REQUIRED_TITLE_PREFIX` | Required title prefix | `required-title-prefix` configured | `"[bot]"` |
1067-
1068-
#### Close Discussion (`close-discussion:`)
1069-
1070-
| Variable | Description | Set When | Example |
1071-
|----------|-------------|----------|---------|
1072-
| `GH_AW_DISCUSSION_REQUIRED_CATEGORY` | Required category name | `required-category` configured | `"Ideas"` |
1073-
| `GH_AW_DISCUSSION_REQUIRED_LABELS` | Required labels (any match) | `required-labels` configured | `"resolved"` |
1074-
| `GH_AW_DISCUSSION_REQUIRED_TITLE_PREFIX` | Required title prefix | `required-title-prefix` configured | `"[ai]"` |
1075-
1076-
#### PR Review Comments (`create-pull-request-review-comment:`)
1077-
1078-
| Variable | Description | Set When | Example |
1079-
|----------|-------------|----------|---------|
1080-
| `GH_AW_PR_REVIEW_COMMENT_SIDE` | Side of diff: LEFT or RIGHT | Always (default: `RIGHT`) | `"RIGHT"` |
1081-
| `GH_AW_PR_REVIEW_COMMENT_TARGET` | Target PR: triggering, *, or number | `target` configured | `"*"` |
1082-
1083-
#### Update Issue (`update-issue:`)
1084-
1085-
| Variable | Description | Set When | Example |
1086-
|----------|-------------|----------|---------|
1087-
| `GH_AW_UPDATE_TARGET` | Target issue: triggering, *, or number | `target` configured | `"*"` |
1088-
| `GH_AW_UPDATE_TITLE` | Allow title updates | `title:` field present | `"true"` |
1089-
| `GH_AW_UPDATE_BODY` | Allow body updates | `body:` field present | `"true"` |
1090-
| `GH_AW_UPDATE_LABELS` | Allow label updates | `labels:` field present | `"true"` |
1091-
1092-
#### Update Discussion (`update-discussion:`)
1093-
1094-
| Variable | Description | Set When | Example |
1095-
|----------|-------------|----------|---------|
1096-
| `GH_AW_UPDATE_TARGET` | Target discussion: triggering, *, or number | `target` configured | `"*"` |
1097-
| `GH_AW_DISCUSSION_ALLOWED_LABELS` | Allowed label changes | `allowed-labels` configured | `"feedback,resolved"` |
1098-
1099-
#### Push to PR Branch (`push-to-pull-request-branch:`)
1100-
1101-
| Variable | Description | Set When | Example |
1102-
|----------|-------------|----------|---------|
1103-
| `GH_AW_PUSH_TARGET` | Target PR: triggering, *, or number | Always (default: `triggering`) | `"*"` |
1104-
| `GH_AW_PUSH_IF_NO_CHANGES` | Behavior when no changes | Always (default: `warn`) | `"warn"`, `"error"`, or `"ignore"` |
1105-
| `GH_AW_PR_TITLE_PREFIX` | Required title prefix | `title-prefix` configured | `"[bot] "` |
1106-
| `GH_AW_PR_LABELS` | Required labels (all must match) | `labels` configured | `"automated"` |
1107-
| `GH_AW_COMMIT_TITLE_SUFFIX` | Suffix for commit titles | `commit-title-suffix` configured | `" [skip ci]"` |
1108-
| `GH_AW_MAX_PATCH_SIZE` | Maximum patch size in KB | Always (default: `1024`) | `1024` |
1109-
| `GH_AW_COMMENT_ID` | Comment ID from activation job | Command-triggered workflow | From activation job output |
1110-
| `GH_AW_COMMENT_REPO` | Repository containing comment | Command-triggered workflow | From activation job output |
1111-
1112-
#### Upload Assets (`upload-assets:`)
1113-
1114-
| Variable | Description | Set When | Example |
1115-
|----------|-------------|----------|---------|
1116-
| `GH_AW_ASSETS_BRANCH` | Target branch name | Always (default: `assets/${{ github.workflow }}`) | `"assets/screenshots"` |
1117-
| `GH_AW_ASSETS_MAX_SIZE_KB` | Maximum file size in KB | Always (default: `10240`) | `10240` |
1118-
| `GH_AW_ASSETS_ALLOWED_EXTS` | Comma-separated allowed extensions | Always (default: `.png,.jpg,.jpeg`) | `".png,.jpg,.svg"` |
1119-
1120-
#### Add Labels (`add-labels:`)
1121-
1122-
| Variable | Description | Set When | Example |
1123-
|----------|-------------|----------|---------|
1124-
| `GH_AW_LABELS_ALLOWED` | Comma-separated allowed labels | `allowed` configured | `"bug,enhancement"` |
1125-
| `GH_AW_LABELS_MAX_COUNT` | Maximum labels to add | Always (default: `3`) | `3` |
1126-
| `GH_AW_LABELS_TARGET` | Target: triggering, *, or number | `target` configured | `"*"` |
1127-
1128-
#### Add Reviewer (`add-reviewer:`)
1129-
1130-
| Variable | Description | Set When | Example |
1131-
|----------|-------------|----------|---------|
1132-
| `GH_AW_REVIEWERS_ALLOWED` | Comma-separated allowed reviewers | `reviewers` configured | `"user1,copilot"` |
1133-
1134-
#### Assign Milestone (`assign-milestone:`)
1135-
1136-
| Variable | Description | Set When | Example |
1137-
|----------|-------------|----------|---------|
1138-
| `GH_AW_MILESTONES_ALLOWED` | Comma-separated allowed milestone titles | `allowed` configured | `"v1.0,v2.0"` |
1139-
1140-
#### Assign to Agent (`assign-to-agent:`)
1141-
1142-
| Variable | Description | Set When | Example |
1143-
|----------|-------------|----------|---------|
1144-
| `GH_AW_DEFAULT_AGENT` | Default agent name | `name` configured | `"copilot"` |
1145-
1146-
#### Assign to User (`assign-to-user:`)
1147-
1148-
| Variable | Description | Set When | Example |
1149-
|----------|-------------|----------|---------|
1150-
| `GH_AW_USERS_ALLOWED` | Comma-separated allowed usernames | `allowed` configured | `"user1,user2"` |
1151-
1152-
#### Link Sub-Issue (`link-sub-issue:`)
1153-
1154-
| Variable | Description | Set When | Example |
1155-
|----------|-------------|----------|---------|
1156-
| `GH_AW_PARENT_REQUIRED_LABELS` | Parent must have any of these labels | `parent-required-labels` configured | `"epic"` |
1157-
| `GH_AW_PARENT_TITLE_PREFIX` | Parent must match this prefix | `parent-title-prefix` configured | `"[Epic]"` |
1158-
| `GH_AW_SUB_REQUIRED_LABELS` | Sub-issue must have any of these labels | `sub-required-labels` configured | `"task"` |
1159-
| `GH_AW_SUB_TITLE_PREFIX` | Sub-issue must match this prefix | `sub-title-prefix` configured | `"[Task]"` |
1160-
| `GH_AW_TEMPORARY_ID_MAP` | Map of temporary IDs to real issue numbers | Issues created with references | From create-issue job output |
1161-
1162-
#### Update Project (`update-project:`)
1163-
1164-
| Variable | Description | Set When | Example |
1165-
|----------|-------------|----------|---------|
1166-
| `GH_AW_PROJECT_GITHUB_TOKEN` | PAT with Projects access (required) | Always | From secrets |
1167-
1168-
#### Update Release (`update-release:`)
1169-
1170-
| Variable | Description | Set When | Example |
1171-
|----------|-------------|----------|---------|
1172-
| `GH_AW_RELEASE_OPERATION` | Operation: replace, append, or prepend | Agent specifies | `"replace"` |
1173-
1174-
#### Code Scanning Alerts (`create-code-scanning-alert:`)
1175-
1176-
| Variable | Description | Set When | Example |
1177-
|----------|-------------|----------|---------|
1178-
| `GH_AW_SECURITY_REPORT_MAX` | Maximum alerts | `max` configured (0=unlimited) | `50` |
1179-
| `GH_AW_SECURITY_REPORT_DRIVER` | Tool name in SARIF | Always | Workflow name or driver field |
1180-
| `GH_AW_WORKFLOW_FILENAME` | Workflow filename for SARIF | Always | Auto-generated |
1181-
1182-
#### No-Op (`noop:`)
1183-
1184-
| Variable | Description | Set When | Example |
1185-
|----------|-------------|----------|---------|
1186-
| `GH_AW_NOOP_MAX` | Maximum no-op messages | Always (default: `1`) | `1` |
1187-
1188-
#### Missing Tool (`missing-tool:`)
1189-
1190-
| Variable | Description | Set When | Example |
1191-
|----------|-------------|----------|---------|
1192-
| `GH_AW_MISSING_TOOL_MAX` | Maximum missing tool reports | `max` configured (0=unlimited) | `0` |
1193-
1194-
### Activation Job Variables
1195-
1196-
When workflows are triggered by comments or reactions, the activation job provides additional context:
1197-
1198-
| Variable | Description | Example |
1199-
|----------|-------------|---------|
1200-
| `GH_AW_COMMENT_ID` | ID of triggering comment | `12345` |
1201-
| `GH_AW_COMMENT_REPO` | Repository containing comment | `owner/repo` |
1202-
| `GH_AW_REACTION` | Reaction that triggered workflow | `"eyes"` |
1203-
| `GH_AW_COMMAND` | Command that triggered workflow | `"test-bot"` |
1204-
| `GH_AW_LOCK_FOR_AGENT` | Lock issue/PR for agent processing | `"true"` |
1205-
1206-
### Safe Inputs Variables
1207-
1208-
When safe inputs are enabled, additional variables are available:
1209-
1210-
| Variable | Description | Example |
1211-
|----------|-------------|---------|
1212-
| `GH_AW_SAFE_INPUTS_PORT` | HTTP server port for safe inputs | From safe-inputs job output |
1213-
| `GH_AW_SAFE_INPUTS_API_KEY` | API key for safe inputs authentication | From safe-inputs job output |
1214-
1215-
### Custom Environment Variables
1216-
1217-
You can add custom environment variables at the safe-outputs level:
1218-
1219-
```yaml
1220-
safe-outputs:
1221-
create-issue:
1222-
env:
1223-
GITHUB_TOKEN: ${{ secrets.CUSTOM_PAT }}
1224-
DEBUG_MODE: "true"
1225-
CUSTOM_API_KEY: ${{ secrets.CUSTOM_API_KEY }}
1226-
```
1227-
1228-
These variables are added to all safe output jobs and take precedence over default values.
1229-
1230-
### Troubleshooting
1231-
1232-
#### Common Issues
1233-
1234-
**Missing required variables**: If a safe output job fails with a missing variable error, ensure the corresponding configuration is present in frontmatter:
1235-
- `GH_AW_WORKFLOW_NAME` → workflow name in frontmatter
1236-
- `GH_AW_AGENT_OUTPUT` → automatically set, indicates missing safe-outputs configuration
1237-
- `GITHUB_TOKEN` → check token configuration and permissions
1238-
1239-
**Token permissions**: Different operations require different tokens:
1240-
- Default `GITHUB_TOKEN` → most operations
1241-
- `GH_AW_PROJECT_GITHUB_TOKEN` or custom token → GitHub Projects v2
1242-
- `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB_TOKEN` → Copilot reviewer/task operations
1243-
- `GH_AW_AGENT_TOKEN` → Agent assignment operations
1244-
1245-
**Cross-repository operations**: Set `GH_AW_TARGET_REPO_SLUG` via `target-repo` configuration. Requires a PAT with access to target repository.
1246-
1247-
**Staged mode not working**: Ensure `GH_AW_SAFE_OUTPUTS_STAGED` is set to `"true"` via `staged: true` configuration.
1248-
1249-
#### Debugging Variables
1250-
1251-
To debug environment variables, add a step to your workflow that prints them:
1252-
1253-
```yaml
1254-
safe-outputs:
1255-
jobs:
1256-
debug:
1257-
description: "Debug environment variables"
1258-
steps:
1259-
- name: Print environment variables
1260-
run: env | grep GH_AW_ | sort
1261-
```
1262-
1263974
## Related Documentation
1264975

1265976
- [Threat Detection Guide](/gh-aw/guides/threat-detection/) - Complete threat detection documentation and examples

0 commit comments

Comments
 (0)