Skip to content
Open
Changes from all commits
Commits
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
37 changes: 17 additions & 20 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,28 +247,25 @@ before changing any AI-facing instruction surface.

## Contributing (Pull Requests)

This repository is commonly worked on from a **fork**. When opening a pull
request, **always target the upstream repository when one is available** — do
not open the PR against the fork unless the user explicitly asks you to.

- Detect the upstream: check `git remote -v`. If an `upstream` remote exists
(e.g. `microsoft/scope`), that is the PR base. The `origin` remote is
typically your personal fork (e.g. `cedricvidal/scope`).
- Push the branch to your fork (`origin`), then open the PR **across forks**
with the upstream as the base:
```bash
gh pr create \
--repo <upstream-owner>/<repo> \
--base main \
--head <fork-owner>:<branch> \
--title "..." --body-file <path>
```
- Only fall back to opening the PR against the fork (`origin`) when there is no
`upstream` remote, or when the user explicitly requests it.
- If the upstream org enforces **SAML SSO** and the PR call fails with a `403`
Before pushing or opening a pull request, inspect `git remote -v` and determine

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Cedric Vidal (@cedricvidal) git remote -v will not provide that information. It will just show if a remote push path is declared. There is no git-native way to do it, except pushing dummy branches.

We should either rely on GitHub CLI, or on a repo file (Either "contributors.yaml" file -where we can put git identities of core devs - or just have a codeteam.local file that is gitignored and we add if we are a core contrib, but cumbersome with devcontainers & worktrees).

Copilot Propose a rewrite of this section using gh repo view OWNER/REPO --json viewerPermission --jq '.viewerPermission'. WRITE, MAINTAIN, or ADMIN means repository-level push access; READ or TRIAGE means they should use a fork.
Do NOT COMMIT your proposal. Write it as a comment in that PR.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested replacement:

Before pushing or opening a pull request, determine your authenticated GitHub permission on `microsoft/scope`:

```sh
gh repo view microsoft/scope --json viewerPermission --jq '.viewerPermission'
  • WRITE, MAINTAIN, or ADMIN: push to an already-configured remote whose URL points to microsoft/scope, then open a same-repository pull request against the intended base branch.
  • READ or TRIAGE: push to an already-configured remote for your fork, then open a cross-fork pull request targeting microsoft/scope and the intended base branch.
  • Use git remote -v only to check which push URLs are configured; it does not establish repository permissions. Never infer access from remote names such as origin or upstream.
  • Never create or configure a fork without the user's explicit approval. If the required remote is not configured, or the permission cannot be determined, stop and ask the user rather than pushing elsewhere.
  • If the target org enforces SAML SSO and the PR call fails with a 403 ("Resource protected by organization SAML enforcement"), stop and ask the user to authorize their token for that org via the SSO link, then retry; do not silently change the target repository.

the user's actual write permission for `microsoft/scope`; do not infer ownership
or access from remote names such as `origin` or `upstream`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Could we add an explicit rule for unverifiable write access? If authentication is missing, expired, or SSO-blocked, the agent should stop and ask rather than treating the failed permission check as evidence that the user lacks write access and choosing the fork flow.


- **Developers with branch write access:** push the branch to an already
configured remote whose URL points to `microsoft/scope`, then open a
same-repository pull request against the intended base branch. Do not use a
fork when direct branch push access is available.
- **Community contributors without branch write access:** push the branch to
their already configured fork, then open a cross-fork pull request targeting
`microsoft/scope` and the intended base branch.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Could we also require an explicit base repository, intended base branch, and head when opening the PR, followed by verification of the returned PR's base and head? This avoids relying on CLI remote-selection defaults when both a fork and microsoft/scope are configured.

- Never create or configure a fork unless the user explicitly requests or
approves it. If the required writable remote is not configured, stop and ask
the user rather than creating a fork or changing the target repository.

- If the target org enforces **SAML SSO** and the PR call fails with a `403`
("Resource protected by organization SAML enforcement"), stop and ask the
user to authorize their token for that org via the SSO link, then retry —
do not silently downgrade to a fork PR.
do not silently change the target repository.

## Documentation Workflow

Expand Down
Loading