The workflow run at
https://github.com/zed-industries/zed/actions/runs/23557683707 succeeded
but threw some warnings for a rather-soon Node.js 20 deprecation (June
2nd).
Hence, this PR updates in that context mentioned workflows to newer
versions from which on the actions will use Node.js 24.
Namely, this updates
- `actions/checkout`
- `actions/create-github-app-token` and
- `peter-evans/create-pull-request`
to their latest version which includes said updates. As for their most
recent versions, all of these actions just updated their versions to
account for said deprecation.
Release Notes:
- N/A
Cleans up a new GitHub Actions workflow.
Before you mark this PR as ready for review, make sure that you have:
- ~~[ ] Added a solid test coverage and/or screenshots from doing manual
testing~~
- [x] Done a self-review taking into account security and performance
aspects
- ~~[ ] Aligned any UI changes with the [UI
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)~~
Release Notes:
- N/A
## Summary
Fork PRs don't have access to repository secrets (`FACTORY_API_KEY`),
causing the docs suggestions workflow to fail when triggered by external
contributor PRs.
This adds a condition to skip the `batch-suggestions` job when the PR
originates from a fork (`github.event.pull_request.head.repo.full_name
!= github.repository`).
## Context
See failing job:
https://github.com/zed-industries/zed/actions/runs/22323201362/job/64586740764
The `pull_request` trigger doesn't pass secrets to workflows running on
fork PRs for security reasons. This is expected GitHub behavior.
Release Notes:
- N/A
## Summary
Fixes the `SyntaxError: Unexpected identifier 'gemini'` error in the
cherry-pick documentation suggestions workflow.
## Problem
The 'Post suggestions as PR comment' step was directly interpolating
markdown content into a JavaScript template literal:
```javascript
const suggestions = `${{ steps.analyze.outputs.suggestions }}`;
```
When the suggestions contained backticks, `${}` sequences, or other
special characters (like the `gemini-3.1-pro-preview` model name in
markdown code blocks), it broke the JavaScript syntax.
## Solution
Write suggestions to a file in `$RUNNER_TEMP` and read it using
`fs.readFileSync()` in the script step. This avoids all GitHub Actions
template interpolation and JavaScript string parsing issues.
## Testing
This should fix the failed run:
https://github.com/zed-industries/zed/actions/runs/22194396124/job/64190762087
Release Notes:
- N/A
Add exponential backoff retry logic (3 attempts with 5s/10s/15s delays)
to the Droid CLI installation and
docs-suggest script execution steps in both the batch-suggestions and
cherry-pick-suggestions jobs.
This handles intermittent Factory API authentication issues that can
cause workflow failures when the API is temporarily unavailable or
rate-limited.
Release Notes:
- N/A
Fixes the workflow failure where `gh auth login --with-token` fails
because `GH_TOKEN` is already set in the environment.
The error was:
```
The value of the GH_TOKEN environment variable is being used for authentication.
To have GitHub CLI store credentials instead, first clear the value from the environment.
```
The fix uses a subshell to unset `GH_TOKEN` before calling `gh auth
login`:
```bash
echo "$GH_TOKEN" | (unset GH_TOKEN && gh auth login --with-token)
```
Release Notes:
- N/A
Fixes two issues in the documentation suggestions workflow:
1. **Shell quoting bug**: PR titles containing quotes (e.g., `agent_ui:
Add the ability to undo "reject all"`) were breaking the shell script
because the title was substituted directly into the script. Moved
`PR_TITLE`, `PR_NUM`, and `OUTPUT_FILE` to environment variables where
special characters are handled safely.
2. **GH CLI auth issue**: The `gh` CLI sometimes fails to auto-detect
`GH_TOKEN` in the environment, causing `gh pr view` and `gh pr diff` to
fail with "Bad credentials". Added explicit `gh auth login --with-token`
in both the batch-suggestions and cherry-pick-suggestions jobs.
Release Notes:
- N/A
Adds scripts and a GitHub Action workflow for automatically suggesting
documentation updates when PRs modify user-facing code.
## Scripts
- **`script/docs-suggest`**: Analyze PRs/commits for documentation needs
using AI
- **`script/docs-suggest-publish`**: Create a PR from batched
suggestions
- **`script/docs-strip-preview-callouts`**: Remove Preview callouts when
shipping to stable
- **`script/test-docs-suggest-batch`**: Testing utility for batch
analysis
## Workflow
The GitHub Action (`.github/workflows/docs_suggestions.yml`) handles two
scenarios:
1. **PRs merged to main**: Suggestions are batched to
`docs/suggestions-pending` branch for the next Preview release
2. **Cherry-picks to release branches**: Suggestions are posted as PR
comments for immediate review
## Callout Types
The system distinguishes between:
- **Additive features** (new commands, settings, UI):
```markdown
> **Preview:** This feature is available in Zed Preview. It will be
included in the next Stable release.
```
- **Behavior modifications** (changed defaults, altered existing
behavior):
```markdown
> **Changed in Preview (v0.XXX).** See [release notes](/releases#0.XXX).
```
Both callout types are stripped by `docs-strip-preview-callouts` when
features ship to stable.
## Example Output
See PR #49190 for example documentation suggestions generated by running
this on PRs from the v0.224 preview window.
## Usage
```bash
# Analyze a PR (auto-detects batch vs immediate mode)
script/docs-suggest --pr 49100
# Dry run to see assembled context
script/docs-suggest --pr 49100 --dry-run
# Create PR from batched suggestions
script/docs-suggest-publish
# Strip callouts for stable release
script/docs-strip-preview-callouts
```
Release Notes:
- N/A
