[no-ci] Support organization-owned forks in AGENTS.md#2378
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
leofang
added
the
PR review get-together
mdboom
left a comment
mdboom
left a comment
There was a problem hiding this comment.
I've had enough run-ins with my agent pushing branches and creating pull requests before they were ready that I've worked really hard to get my agent to /never/ write anything in a remote location without my consent (and I prefer to be in the driver's seat even now for those steps).
I'm worried that a lot of the language here will encourage my agent to act too autonomously again. We should instead frame it in terms of things we want it /not/ to do (don't push to a fork that can't be the source of the PR you are trying to create), rather than things /to do/ (use gh pr to create PRs). To put it another way -- this is shared context we want everyone to agree on to collaborate well together. It's not intended to prescribe /how/ to accomplish that. A pre-AI analogy would be: we all agree to write standard text files and share them with git. We don't have to agree on what editor we are using or what git tool we use.
Therefore, I think the only required change here should be:
All branch creation and pushes must go to the contributor's
personal fork.
changes to:
Branch creation and pushes must not go directly to the canonical upstream fork. Use the user's personal fork, or if that is not supported as an official fork of upstream, use a intra-repo fork "owned" by the user. Confirm that the push target is a fork of the base repository and is not the base repository itself.
| force-pushing, or deleting branches; those actions require separate explicit | ||
| authorization. | ||
|
|
||
| Use `gh pr create` when it can identify the fork unambiguously. Always select |
There was a problem hiding this comment.
So if the agent can identify the fork unambiguously, it is free to create a PR? Certainly that's not what's intended, but 100% can imagine the agent doing the wrong thing here.
| If you are unsure which label or milestone to use, inspect the base repository | ||
| with `gh label list --repo "${BASE_REPO}"` and `gh api | ||
| "repos/${BASE_REPO}/milestones" --jq '.[].title'`, then pick the best match. |
There was a problem hiding this comment.
| If you are unsure which label or milestone to use, inspect the base repository | |
| with `gh label list --repo "${BASE_REPO}"` and `gh api | |
| "repos/${BASE_REPO}/milestones" --jq '.[].title'`, then pick the best match. | |
| If you are unsure which label or milestone to use, don't guess. Flag it for the user and have them fill it in. |
| Do not push to the canonical repository unless the user explicitly requests, | ||
| in the current conversation, a push to a specific branch in that repository. |
There was a problem hiding this comment.
This opens up a window for mistakes. What's wrong with saying "Never push to the canonical repository"? The user can always do it by hand anyway. None of us should be running with write access to the canonical repository in our local checkouts -- that's too dangerous.
| Treat the canonical repository used as the pull-request base as read-only by | ||
| default. Push branches and commits to an approved fork, which may be owned by |
There was a problem hiding this comment.
| Treat the canonical repository used as the pull-request base as read-only by | |
| default. Push branches and commits to an approved fork, which may be owned by | |
| Treat the canonical repository used as the pull-request base as read-only. Push branches and commits to an approved fork, which may be owned by |
| Obtain the node IDs with `gh api "repos/${BASE_REPO}" --jq '.node_id'` and | ||
| `gh api "repos/${HEAD_REPO}" --jq '.node_id'`. Then create the PR with | ||
| `headRepositoryId` to identify the organization-owned fork: | ||
|
|
||
| ``` | ||
| gh api graphql \ | ||
| -f repositoryId="${BASE_REPO_ID}" \ | ||
| -f headRepositoryId="${HEAD_REPO_ID}" \ | ||
| -f baseRefName="${BASE_BRANCH}" \ | ||
| -f headRefName="${HEAD_BRANCH}" \ | ||
| -f title="<title>" \ | ||
| -F body="@${BODY_FILE}" \ | ||
| -F draft=false \ | ||
| -f query=' | ||
| mutation CreatePullRequest( | ||
| $repositoryId: ID! | ||
| $headRepositoryId: ID! | ||
| $baseRefName: String! | ||
| $headRefName: String! | ||
| $title: String! | ||
| $body: String! | ||
| $draft: Boolean! | ||
| ) { | ||
| createPullRequest(input: { | ||
| repositoryId: $repositoryId | ||
| headRepositoryId: $headRepositoryId | ||
| baseRefName: $baseRefName | ||
| headRefName: $headRefName | ||
| title: $title | ||
| body: $body | ||
| draft: $draft | ||
| }) { | ||
| pullRequest { number url } | ||
| } | ||
| }' \ | ||
| --jq '.data.createPullRequest.pullRequest' | ||
| ``` |
There was a problem hiding this comment.
What's the rationale for including detailed information about the GraphQL API here? Certainly the agent has access to the docs, and I worry this would bitrot.
3 participants
Description
This updates the repository-wide agent guidance to support approved forks owned by either personal accounts or organizations.
The existing guidance assumes that every contributor uses a personal fork and can always open a pull request with
gh pr create. That command currently cannot identify some renamed organization-owned forks (cli/cli#10093), even though GitHub's GraphQL API supports selecting the head repository explicitly throughheadRepositoryId.The update:
OWNER/REPOSITORYnames;gh pr createwhen it can identify the fork unambiguously;headRepositoryIdfallback for organization-owned forks; andThe wording is intentionally repository-neutral so the guidance remains applicable across supported development setups.
Review focus:
This PR does not have an associated GitHub issue.
Validation:
pre-commit run --files AGENTS.mdgit diff --checkChecklist