Skip to content

docs: add pre-step data-fetching pattern to create-agentic-workflow.md #24685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 6 commits into from
Apr 5, 2026
Merged

docs: add pre-step data-fetching pattern to create-agentic-workflow.md #24685

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5c01816
Initial plan
Copilot Apr 5, 2026
3cccd00
docs: document pre-step data-fetching pattern in create-agentic-workf…
Copilot Apr 5, 2026
41f63b5
docs: add GH_TOKEN env and proper permissions to pre-step template sn…
Copilot Apr 5, 2026
c1a30ba
docs: optimize pre-step data-fetching section for agent consumption, …
Copilot Apr 5, 2026
e012914
docs: suggest jq for efficient JSON filtering in pre-step data fetching
Copilot Apr 5, 2026
0b4ff6a
docs: mention tools.agentic-workflows for logs and audit in pre-step …
Copilot Apr 5, 2026
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
57 changes: 57 additions & 0 deletions .github/aw/create-agentic-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -705,6 +705,63 @@ When creating workflows that involve coding agents operating in large repositori
- Documentation updates for multiple services
- Dependency updates across microservices

### Pre-step Data Fetching

Use a deterministic `steps:` block to download, trim, and store heavy data before the agent runs. The agent reads local files instead of making repeated API calls, staying within its token budget.

**Rules:**
- Always set `env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` on every step that calls `gh` — the token is not injected automatically.
- Write output to `/tmp/gh-aw/agent/` (canonical agent data directory).
- Trim large blobs before writing (`tail -N`).
- Add `permissions: actions: read` when reading workflow logs or artifacts.
- Use `jq` to filter JSON responses before writing them to disk — extract only the fields the agent needs and keep file sizes small.

**Template (CI log analysis):**

```yaml
---
on:
workflow_run:
workflows: ["CI"]
types: [completed]
permissions:
contents: read
actions: read # required for gh run view / gh run download
tools:
github:
toolsets: [default]
cache-memory: true # persist pre-fetched data across runs (dedup, trending)
steps:
- name: Fetch CI logs
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
RUN_ID: ${{ github.event.workflow_run.id }}
run: |
mkdir -p /tmp/gh-aw/agent
gh run view "$RUN_ID" --log > /tmp/gh-aw/agent/ci-logs.txt 2>&1 || true
tail -500 /tmp/gh-aw/agent/ci-logs.txt > /tmp/gh-aw/agent/ci-logs-trimmed.txt
safe-outputs:
add-comment:
max: 1
---

Analyze `/tmp/gh-aw/agent/ci-logs-trimmed.txt`. Identify the root cause and post a comment to the triggering PR.
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template prompt says to “post a comment to the triggering PR”, but workflow_run can be triggered by non-PR runs (e.g., pushes) where there is no associated PR to comment on. Consider updating the instructions to handle the “no PR” case explicitly (e.g., noop, or comment on the run/commit instead).

Suggested change
Analyze `/tmp/gh-aw/agent/ci-logs-trimmed.txt`. Identify the root cause and post a comment to the triggering PR.
Analyze `/tmp/gh-aw/agent/ci-logs-trimmed.txt`. Identify the root cause and determine whether the triggering `workflow_run` is associated with a pull request. If it is, post a comment to that PR. If no PR is associated with the run, skip commenting.

Copilot uses AI. Check for mistakes.

Check `/tmp/gh-aw/cache-memory/seen-runs.json` for previously seen run IDs; skip if already processed and append the current run ID when done.
```

**Use cases:**

| Scenario | Step snippet |
|---|---|
| Deployment logs (Heroku/Vercel/Railway) | `heroku logs --tail --num 200 --app ${{ vars.HEROKU_APP }} > /tmp/gh-aw/agent/deploy-logs.txt` |
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Heroku example uses heroku logs --tail ..., which will continue streaming and can cause the pre-step to hang until the job times out. For a bounded, deterministic pre-fetch, use a non-tailing invocation that exits after a fixed number of lines (or add an explicit timeout).

Suggested change
| Deployment logs (Heroku/Vercel/Railway) | `heroku logs --tail --num 200 --app ${{ vars.HEROKU_APP }} > /tmp/gh-aw/agent/deploy-logs.txt` |
| Deployment logs (Heroku/Vercel/Railway) | `heroku logs --num 200 --app ${{ vars.HEROKU_APP }} > /tmp/gh-aw/agent/deploy-logs.txt` |

Copilot uses AI. Check for mistakes.
| Build / test output | `npm ci 2>&1 \| tail -200 > /tmp/gh-aw/agent/build.txt && npm run test -- --reporter=json > /tmp/gh-aw/agent/test.json 2>&1 \|\| true` |
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The build/test snippet pipes npm ci into tail, which means the pipeline exit status will come from tail (so npm ci failures may be ignored unless pipefail is set). Consider adjusting the example so failures are handled intentionally (e.g., enable set -o pipefail, or avoid masking the command’s exit code while still trimming output).

Suggested change
| Build / test output | `npm ci 2>&1 \| tail -200 > /tmp/gh-aw/agent/build.txt && npm run test -- --reporter=json > /tmp/gh-aw/agent/test.json 2>&1 \|\| true` |
| Build / test output | `set -o pipefail && npm ci 2>&1 \| tail -200 > /tmp/gh-aw/agent/build.txt && npm run test -- --reporter=json > /tmp/gh-aw/agent/test.json 2>&1 \|\| true` |

Copilot uses AI. Check for mistakes.
| Workflow run artifact | `gh run download "$RUN_ID" --name test-results --dir /tmp/gh-aw/agent/artifacts/ \|\| true` |
| Filter JSON API response | `gh api repos/{owner}/{repo}/issues --jq '[.[] \| {number,title,state,labels:[.labels[].name]}]' > /tmp/gh-aw/agent/issues.json` |
| Agentic workflow run logs | No shell step needed — add `tools: agentic-workflows:` and the agent uses `logs` and `audit` commands directly |

**`cache-memory` tip:** Add `cache-memory: true` under `tools:` to persist pre-fetched data across runs. This enables deduplication (skip already-diagnosed run IDs), trending (compare metrics over time), and avoids redundant downloads on retries. The agent reads and writes `/tmp/gh-aw/cache-memory/`. Use `jq` to update the dedup file efficiently — for example `jq '. + ["'"$RUN_ID"'"]' /tmp/gh-aw/cache-memory/seen-runs.json > /tmp/seen-runs.tmp && mv /tmp/seen-runs.tmp /tmp/gh-aw/cache-memory/seen-runs.json`. See `.github/aw/memory.md` for full configuration options.
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The jq one-liner assumes /tmp/gh-aw/cache-memory/seen-runs.json already exists and contains valid JSON; on a first run it likely won’t, so the example will fail. Consider showing an initialization/fallback ([] if missing) and, if you want to guarantee deduplication, ensure the updated array is unique.

Suggested change
**`cache-memory` tip:** Add `cache-memory: true` under `tools:` to persist pre-fetched data across runs. This enables deduplication (skip already-diagnosed run IDs), trending (compare metrics over time), and avoids redundant downloads on retries. The agent reads and writes `/tmp/gh-aw/cache-memory/`. Use `jq` to update the dedup file efficiently — for example `jq '. + ["'"$RUN_ID"'"]' /tmp/gh-aw/cache-memory/seen-runs.json > /tmp/seen-runs.tmp && mv /tmp/seen-runs.tmp /tmp/gh-aw/cache-memory/seen-runs.json`. See `.github/aw/memory.md` for full configuration options.
**`cache-memory` tip:** Add `cache-memory: true` under `tools:` to persist pre-fetched data across runs. This enables deduplication (skip already-diagnosed run IDs), trending (compare metrics over time), and avoids redundant downloads on retries. The agent reads and writes `/tmp/gh-aw/cache-memory/`. Use `jq` to update the dedup file efficiently — for example `jq -n --arg run_id "$RUN_ID" '((input // []) + [$run_id]) | unique' < <(cat /tmp/gh-aw/cache-memory/seen-runs.json 2>/dev/null || printf '[]') > /tmp/seen-runs.tmp && mv /tmp/seen-runs.tmp /tmp/gh-aw/cache-memory/seen-runs.json`. See `.github/aw/memory.md` for full configuration options.

Copilot uses AI. Check for mistakes.

## Issue Form Mode: Step-by-Step Workflow Creation

When processing a GitHub issue created via the workflow creation form, follow these steps:
Expand Down
79 changes: 10 additions & 69 deletions pkg/agentdrain/data/default_weights.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,28 +39,7 @@
"id": 5,
"size": 1,
"stage": "error",
"template": [
"stage=error",
"reason=The",
"Serena",
"MCP",
"server",
"is",
"not",
"available",
"in",
"this",
"environment.",
"No",
"serena-*",
"tools",
"are",
"registered.",
"tool=Serena",
"MCP",
"server",
"type=missing_tool"
]
"template": ["stage=error", "reason=The", "Serena", "MCP", "server", "is", "not", "available", "in", "this", "environment.", "No", "serena-*", "tools", "are", "registered.", "tool=Serena", "MCP", "server", "type=missing_tool"]
},
Comment on lines 39 to 43
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description focuses on documentation changes, but this file is also modified (formatting/serialization changes). Please either mention this change in the PR description or split it into a separate PR so reviewers understand why default weights data is being updated.

Copilot uses AI. Check for mistakes.
{
"id": 6,
Expand Down Expand Up @@ -234,12 +213,7 @@
],
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -285,21 +259,12 @@
"id": 1,
"size": 100,
"stage": "finish",
"template": [
"stage=finish",
"\u003c*\u003e",
"tokens=\u003cNUM\u003e"
]
"template": ["stage=finish", "\u003c*\u003e", "tokens=\u003cNUM\u003e"]
}
],
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -345,21 +310,12 @@
"id": 1,
"size": 72,
"stage": "plan",
"template": [
"stage=plan",
"errors=\u003cNUM\u003e",
"turns=\u003cNUM\u003e"
]
"template": ["stage=plan", "errors=\u003cNUM\u003e", "turns=\u003cNUM\u003e"]
}
],
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -403,12 +359,7 @@
"clusters": null,
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -452,12 +403,7 @@
"clusters": null,
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -1607,12 +1553,7 @@
],
"config": {
"Depth": 4,
"ExcludeFields": [
"session_id",
"trace_id",
"span_id",
"timestamp"
],
"ExcludeFields": ["session_id", "trace_id", "span_id", "timestamp"],
"MaskRules": [
{
"Name": "uuid",
Expand Down Expand Up @@ -1652,4 +1593,4 @@
},
"next_id": 15
}
}
}
Loading