Agentic workflow for submitting documentation PRs#37765
Agentic workflow for submitting documentation PRs#37765roji wants to merge 1 commit intodotnet:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new agentic GitHub Actions workflow intended to generate documentation changes and open draft PRs against dotnet/EntityFramework.Docs when triggered via a /doc slash command on an issue comment.
Changes:
- Added a gh-aw workflow definition (
create-docs-pr.md) describing the desired documentation PR behavior and authoring guidance. - Added the generated, locked GitHub Actions workflow (
create-docs-pr.lock.yml) that executes Copilot CLI + safe-outputs to create PRs/comments. - Marked
*.lock.ymlworkflows as generated in.gitattributes(and configured merge behavior), and added an actions SHA lock file under.github/aw/.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| .github/workflows/create-docs-pr.md | Source gh-aw markdown workflow definition and instructions for authoring docs PRs. |
| .github/workflows/create-docs-pr.lock.yml | Generated workflow implementation (jobs, permissions, safe-outputs plumbing). |
| .github/aw/actions-lock.json | Locks specific action SHAs used by the workflow tooling. |
| .gitattributes | Marks generated workflow lock files and sets merge strategy for them. |
| GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} | ||
| GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"hide_older_comments\":true,\"max\":1},\"create_pull_request\":{\"base_branch\":\"${{ github.ref_name }}\",\"draft\":true,\"fallback_as_issue\":false,\"max\":1,\"max_patch_size\":1024,\"reviewers\":[\"roji\"],\"target-repo\":\"dotnet/EntityFramework.Docs\"},\"missing_data\":{},\"missing_tool\":{}}" | ||
| with: | ||
| github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} |
There was a problem hiding this comment.
The safe-outputs frontmatter declares github-token: ${{ secrets.ROJI_TOKEN }} for creating PRs in dotnet/EntityFramework.Docs, but the actions/github-script step running safe_output_handler_manager.cjs uses ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}. GITHUB_TOKEN typically won’t have access to a different repository, so PR creation may fail unless GH_AW_GITHUB_TOKEN is specially provisioned. Consider using the same cross-repo token (or a GitHub App token) for the handler step as well.
| github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} | |
| github-token: ${{ secrets.ROJI_TOKEN }} |
| issues: read | ||
| pull-requests: read |
There was a problem hiding this comment.
The frontmatter permissions are set to read-only, but this workflow needs to write (e.g., add reactions/comments on the triggering issue and create PRs). Please update the declared permissions to match what the generated workflow actually requires (at minimum issues: write and likely pull-requests: write, discussions: write if used), so future recompiles/maintenance don’t drift or confuse reviewers.
| issues: read | |
| pull-requests: read | |
| issues: write | |
| pull-requests: write |
| ``` | ||
|
|
||
| * Find the "what's new" page for the latest major release (typically `core/what-is-new/ef-core-11.0`, adjusting for the version), and add a **brief** section on the feature - just the minimum needed to make the user understand what it's about; include a minimal code sample as well if relevant. At the bottom, add a line such as "For more information on X, see the documentation" linking to the full docs added above. | ||
| * For both the full docs and the what's new documentation, do not simply create a new section; first check to see if there's an existing section that already covers related/similar functionality; if there is, either merge the new content into it or place the new section new to it. |
There was a problem hiding this comment.
This sentence is grammatically incorrect: "place the new section new to it". It reads like a typo and should be corrected (e.g., "next to it").
| * For both the full docs and the what's new documentation, do not simply create a new section; first check to see if there's an existing section that already covers related/similar functionality; if there is, either merge the new content into it or place the new section new to it. | |
| * For both the full docs and the what's new documentation, do not simply create a new section; first check to see if there's an existing section that already covers related/similar functionality; if there is, either merge the new content into it or place the new section next to it. |
| ## Additional instructions | ||
|
|
||
| * The commit in the submitted PR should have a title of the form "Document X", where X is the name of the feature as it appears in the title of the originating issue. If the title is too long, for a git commit, make it shorter. The commit body should be of the form "Document Y", where Y is a link to the originating issue. | ||
| * If you encounter any error or issue, post a comment on the triggering PR detailing the problem(s) you encountered. |
There was a problem hiding this comment.
This workflow is triggered for issue comments (and explicitly excludes PR comments). The instruction to "post a comment on the triggering PR" is inconsistent; it should refer to the triggering issue (or the triggering discussion, if supported).
| * If you encounter any error or issue, post a comment on the triggering PR detailing the problem(s) you encountered. | |
| * If you encounter any error or issue, post a comment on the triggering issue detailing the problem(s) you encountered. |
| (needs.pre_activation.outputs.activated == 'true') && (((github.event_name == 'issue_comment') && ((github.event_name == 'issue_comment') && | ||
| (((startsWith(github.event.comment.body, '/doc ')) || (github.event.comment.body == '/doc')) && (github.event.issue.pull_request == null)))) || | ||
| (!(github.event_name == 'issue_comment'))) | ||
| runs-on: ubuntu-slim |
There was a problem hiding this comment.
runs-on: ubuntu-slim isn’t a standard GitHub-hosted runner label (unlike ubuntu-latest/ubuntu-24.04). Unless this repo has a self-hosted runner labeled ubuntu-slim, these jobs will fail to start. Consider switching to a GitHub-hosted runner label or explicitly using self-hosted with the appropriate labels.
| runs-on: ubuntu-slim | |
| runs-on: ubuntu-latest |
| repository: dotnet/EntityFramework.Docs | ||
| token: ${{ secrets.ROJI_TOKEN }} | ||
| persist-credentials: false | ||
| fetch-depth: 1 |
There was a problem hiding this comment.
The workflow instructions say to target a docs-repo branch derived from the issue’s preview/rc label, but this checkout step doesn’t specify ref: and uses fetch-depth: 1, which will only fetch the default branch. If the PR needs to be based on / target a non-default branch, the checkout should fetch and checkout that branch (and/or fetch all refs needed).
| fetch-depth: 1 | |
| ref: ${{ github.ref_name }} | |
| fetch-depth: 0 |
| GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} | ||
| GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"hide_older_comments\":true,\"max\":1},\"create_pull_request\":{\"base_branch\":\"${{ github.ref_name }}\",\"draft\":true,\"fallback_as_issue\":false,\"max\":1,\"max_patch_size\":1024,\"reviewers\":[\"roji\"],\"target-repo\":\"dotnet/EntityFramework.Docs\"},\"missing_data\":{},\"missing_tool\":{}}" |
There was a problem hiding this comment.
GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG hardcodes create_pull_request.base_branch to ${{ github.ref_name }}, which won’t match the documented requirement to choose the docs target branch from the issue’s preview/rc label. This will likely create docs PRs against the wrong base branch. Consider removing this hardcoded base branch and letting the agent/tool supply the computed base branch, or compute it in the workflow before calling the safe outputs handler.
|
Closing in favor of dotnet/EntityFramework.Docs#5274, as @AndriySvyryd prefers we don't use slash commands. |
2 participants
No description provided.