docs inconsistency for environment creation and unreasonable permissions required

[kewalaka]

Platform: GitHub Enterprise Cloud (*.ghe.com), reproduced 2026-07-11

---

Documentation inconsistency

The permissions required for GitHub Apps summary page lists PUT /repos/{owner}/{repo}/environments/{environment_name} under the environments permission (write). The endpoint-specific documentation appears to contradicts this, stating administration: write is required.

What I expected

A GitHub App with environments: write should be able to create deployment environments via PUT /repos/{owner}/{repo}/environments/{environment_name}. The environments permission exists specifically to manage deployment environments — granting it at write level implies CRUD access.

Behaviour

PUT /repos/{owner}/{repo}/environments/{environment_name} returns 403 Resource not accessible by integration with an App token that has:

{
  "environments": "write",
  "secrets": "write",
  "actions_variables": "write",
  "metadata": "read"
}

Adding administration: write resolves the 403. Confirmed via direct API test with a minted installation access token.

Why this matters

Least privilege

Requested change

Either

1. Make environments: write sufficient to create/update environments, or
2. If administration: write is genuinely required by design, document why and update the permissions summary page to reflect this accurately

I prefer number 1 😄

Related

• integrations/terraform-provider-github#3121 — related but separate; covers actions: read requirement for the GET endpoint