GitHub.com API guarantees: exact ref CAS, write fencing and deployment suppression

[PhD-Cho]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

API

Body

I'm looking for documentation or an appropriate GitHub technical contact to clarify whether the following guarantees are available on GitHub.com, including any plan restrictions. This is a capability question, not a vulnerability report or an active incident.

The use case is a recovery workflow that creates a small set of Git objects and then updates one branch reference. Before implementing it, I need to distinguish supported provider guarantees from controls that would only apply to my own client. A partial answer with an official reference would be helpful; an explicit unsupported answer is also useful.

1. Repository-wide write control. Is there a supported GitHub-enforced guard covering every write credential and channel, including PATs, GitHub Apps, SSH/deploy keys, administrators, automation, and REST Git object/ref writes? Can it also block or serialize changes to relevant permissions, settings, and integrations while the guard is active? A proxy holding only its own credential would not cover this requirement.

2. Owner, generation and expiry checked when accepting a write. Can GitHub atomically validate the current execution owner, a monotonically increasing execution generation, and expiry at the point where a write is accepted? If ownership changes while the request is in flight, can a stale or expired request be rejected without a mutation, event, or trigger? Client-side checks before sending would not provide that guarantee.

3. Durable prevention of deployment effects. Can a write's acceptance atomically establish an event-specific prohibition on deployment/production effects before the write becomes visible or triggers are queued? It must survive client failure and guard expiry, including delayed polling, webhook redelivery, restarted consumers, and connected external deployment providers. Please distinguish GitHub-controlled effects from anything outside GitHub's control.

4. Complete integration inventory and coherent configuration. Is there an authoritative inventory covering relevant Apps, webhooks, Actions, Pages, environments, deployments, checks/status integrations, and external provider connections? Can a common configuration version or snapshot span paginated reads and stay protected through the guarded write? Which guarantees differ between personal and organization repositories, and what permissions are required?

5. Exact expected-old SHA for a reference update. The REST Update a reference documentation lists sha and force; force:false checks fast-forward compatibility. Is there a documented exact expected-old SHA condition for this endpoint, or a provider-enforced equivalent excluding all concurrent writers between the tip read and update? I am not assuming If-Match support or treating GET followed by PATCH as atomic compare-and-swap. An alternative API may be relevant, but please identify it separately and state its limitations.

6. Evidence and recovery after an uncertain outcome. For any supported mechanisms above, are there authenticated acceptance/event identifiers, immutable or versioned readback records, and documented recovery semantics for a lost response, controller crash, or server failover? The workflow must resolve the outcome before retrying a publication request.

References reviewed:

• REST Update a reference
• Available rules for rulesets
• Deployments and environments
• Repository webhooks API

For any answer, please identify the applicable endpoint/product, API version, plan, documented guarantee, and limitations. If this needs a GitHub product team or a separate commercial arrangement, which official contact can confirm feasibility before purchase? I am asking whether these capabilities exist, not asserting that GitHub promises them.

[AshrafMorningstar]

Repository-wide write control
GitHub does not support a global write lock spanning all channels (PATs, Apps, SSH, administrators) and configuration endpoints simultaneously. Branch protection rules can restrict pushes, but repository administrators can bypass these restrictions or modify the rulesets directly. There is no API-level transactional freeze.
Owner, generation, and expiry checks
GitHub does not provide server-side evaluation of execution generations, distributed fencing tokens, or lease expirations at the infrastructure layer. Expiration and ownership logic must be evaluated client-side before issuing a write, leaving a fundamental race condition window if your client halts between validation and execution.
Durable prevention of deployment effects
Atomic suppression of deployment effects upon write acceptance is unsupported. GitHub's architecture queues triggers (webhooks, Actions) asynchronously the moment a reference updates. You cannot pass a flag to a Git push or API write instructing GitHub to temporarily suppress downstream triggers or hide the event from external polling systems.
Complete integration inventory and coherent configuration
There is no snapshot isolation across GitHub's APIs. While you can query webhooks, Actions, and Environments, reading paginated endpoints does not guarantee state coherence; configurations can mutate between reading page 1 and page 2. Additionally, GitHub cannot provide an authoritative inventory of external systems that integrate via polling rather than webhooks.
Exact expected-old SHA for a reference update
This capability exists, but the REST API is the wrong tool. REST's force: false only checks for fast-forward compatibility, not an exact target match. True compare-and-swap (CAS) requires:

• The GraphQL API: The updateRefs mutation accepts a beforeOid parameter that rejects the atomic update if the reference does not currently match the specified SHA.
• The Git Protocol: Standard Git operations using --force-with-lease=:.
  Evidence and recovery after uncertain outcome
  GitHub does not support client-provided idempotency keys for reference updates. The GraphQL clientMutationId is simply echoed back, offering no server-side deduplication. If a request times out or your client crashes, recovery relies entirely on the CAS mechanism: you must re-fetch the remote tip and assume success if it matches your target state.
  Your recovery workflow attempts to extract strict consistency, atomic snapshot isolation, and distributed lock management from an eventually consistent, asynchronous platform. Expecting GitHub to enforce fencing tokens and suppress downstream deployments at the infrastructure layer is an architectural mismatch. Deployment suppression and concurrency control must be enforced by your own downstream consumers and deployment controllers, rather than relying on GitHub to act as a transactional lock manager.