Copilot Code Review GraphQL: Change Settings and Restore Inheritance

You administer a repository and want Copilot reviews to use custom instructions while keeping MCP tools out of those reviews. You also need a reliable way back to the previous configuration. Copilot code review GraphQL exposes the settings needed for that round trip, but successful recovery depends on saving the configured value separately from the effective value.

This tutorial is for repository administrators with an existing authenticated GitHub API client and a disposable repository. You will read its settings, select BALANCED only when available, change three fields, inspect the response, read them again, and restore the saved state. The queries, variables and responses below form one complete illustrative case, task:review-settings-01. No API operations were executed for this article.

GitHub’s November 6, 2026 announcement introduced API management across enterprise, organization and repository scopes. The useful lesson is narrower: implement one repository settings transaction with an explicit recovery operation.

Establish the repository and the recovery boundary

1. Choose an existing disposable repository that you administer.
2. Open your already authenticated GraphQL client using its existing GitHub connection.
3. Confirm that you can retain the complete query response before submitting a mutation.
4. Arrange a quiet editing window so another administrator does not change the same settings during the exercise.

The illustrative repository is example-labs/review-settings-sandbox. Replace those two values with the owner and name of your disposable repository. Authentication setup remains outside this tutorial’s scope. Keep your existing connection and identity throughout the exercise.

GitHub’s GraphQL call guide documents personal access tokens, GitHub Apps and OAuth apps as authentication methods. It also explains that missing permissions produce an error identifying the required scopes or permissions. Use an existing identity with the access appropriate to your organization rather than treating a readable public repository as sufficient authorization.

The Repository schema specifically says repositoryCopilotCodeReviewSettings requires repository administration access. The announcement separately documents Administration: read and Administration: write for the repository REST settings endpoints and their support for GitHub Apps and fine-grained personal access tokens. Those REST permission statements should not be mistaken for a complete GraphQL authorization specification. For this tutorial, the supported prerequisite is an authenticated repository administrator whose GraphQL request succeeds. Stop on authorization errors.

Keep the change boundary small. You will submit reviewEffort, customInstructionsEnabled and mcpEnabled, and leave severityFilter out of the mutation. GitHub documents that omitted repository settings are unchanged. That property lets you recover the fields you deliberately changed without copying every readable field into a write operation.

This integration complements the separate question of review authority covered in AI PR Review Agent Policy. Settings readback establishes configuration state; it does not establish whether a pull request should merge.

Read the original state before choosing an effort

1. Paste the following operation into your client’s GraphQL operation editor.
2. Paste the accompanying JSON into its variables editor.
3. Run the query and retain the entire response as the original snapshot.
4. Stop if the response contains errors, a null repository, or null settings.

query ReadReviewSettings($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    id
    nameWithOwner
    repositoryCopilotCodeReviewSettings {
      availableReviewEfforts
      reviewEffort {
        configured
        effective
      }
      customInstructionsEnabled
      mcpEnabled
      severityFilter
    }
  }
}

{
  "owner": "example-labs",
  "name": "review-settings-sandbox"
}

The repository query takes an owner login and repository name. Its id field supplies the node ID required by the later mutation. Do not substitute the numeric database ID, construct a node ID from the repository name, or reuse an ID from another exercise. Confirm nameWithOwner before moving forward; that human-readable field catches a wrong target before it becomes a wrong write.

The following response is illustrative, not observed. The symbolic node ID makes its teaching role explicit. Every mutation example using REPOSITORY_NODE_ID_FROM_READ requires replacement with the exact id returned by your own query. The available efforts and boolean values must likewise come from your response, not from this sample.

{
  "data": {
    "repository": {
      "id": "REPOSITORY_NODE_ID_FROM_READ",
      "nameWithOwner": "example-labs/review-settings-sandbox",
      "repositoryCopilotCodeReviewSettings": {
        "availableReviewEfforts": ["LITE", "BALANCED"],
        "reviewEffort": {
          "configured": null,
          "effective": "LITE"
        },
        "customInstructionsEnabled": false,
        "mcpEnabled": true,
        "severityFilter": "NO_FILTER"
      }
    }
  }
}

Read the fields as different kinds of information. availableReviewEfforts lists the choices currently settable for this repository. configured describes the repository’s stored effort, subject to the null qualification below. effective describes the effort reviews would use when the requester and pull request do not choose one. It is therefore a resolved default, not a promise about every future review.

The Copilot GraphQL reference gives configured an important ambiguity: null can mean inheritance, or a stored effort that is currently unavailable. Do not silently translate every null into proof that no override exists. This guide’s inherited-state example assumes you have separately confirmed that the disposable repository is intentionally inheriting. If that history is unknown, use the boolean-only variant later in the guide and omit reviewEffort from both writes.

For example, an administrator’s reliable record that they intentionally selected inheritance can support this exercise’s starting assumption. Merely seeing LITE in the effective field cannot. The same resolved value could arise through another configuration history, and the documented read does not reveal an unavailable stored enum. Record whether your decision rests on confirmed history or an unresolved null before selecting the mutation path.

Illustrative decision matrix: omission preserves the current setting, BALANCED sets an available override, and INHERIT clears the repository value. Source: GitHub Copilot GraphQL reference, read November 7, 2026.

Apply one populated case

1. Check that BALANCED appears in your actual availableReviewEfforts list.
2. Confirm that the saved booleans are complete and that the original effort is recoverable.
3. Populate the mutation variables with the exact repository node ID from the read.
4. Submit the mutation once and inspect its complete response before continuing.

The worked example uses an intentionally inherited repository whose effective effort is LITE. It temporarily stores BALANCED, enables repository custom instructions and disables review access to MCP servers. These are illustrative choices for demonstrating the API, not a recommendation that every repository should use the same combination.

Input	Action	Expected result
task:review-settings-01: example-labs/review-settings-sandbox; confirmed inheritance; configured=null; effective=LITE; available=[LITE,BALANCED]; customInstructionsEnabled=false; mcpEnabled=true	Save the original response; call updateRepositoryCopilotCodeReviewSettings with reviewEffort=BALANCED, customInstructionsEnabled=true and mcpEnabled=false; omit severityFilter	Illustrative expected observation: returned settings and an independent read show configured=BALANCED, effective=BALANCED, customInstructionsEnabled=true and mcpEnabled=false; severityFilter remains NO_FILTER
task:review-settings-01 recovery: original effort confirmed inherited, original customInstructionsEnabled=false and mcpEnabled=true	Call the same mutation with reviewEffort=INHERIT and the two original booleans; omit severityFilter again	Illustrative expected observation: configured returns null, the original booleans return, and effective resolves from the current inherited default; it is LITE if that default has not changed

Use this complete mutation for both the change and recovery. Its input variable has the documented UpdateRepositoryCopilotCodeReviewSettingsInput type. Its payload requests the settings you need to inspect rather than returning only a client identifier.

mutation SetReviewSettings(
  $input: UpdateRepositoryCopilotCodeReviewSettingsInput!
) {
  updateRepositoryCopilotCodeReviewSettings(input: $input) {
    settings {
      availableReviewEfforts
      reviewEffort {
        configured
        effective
      }
      customInstructionsEnabled
      mcpEnabled
      severityFilter
    }
  }
}

Apply variables:

{
  "input": {
    "repositoryId": "REPOSITORY_NODE_ID_FROM_READ",
    "reviewEffort": "BALANCED",
    "customInstructionsEnabled": true,
    "mcpEnabled": false
  }
}

The quoted BALANCED value is correct inside JSON variables. When an enum is written directly inside a GraphQL operation, it is unquoted. GitHub’s call guide explains this distinction: the variable document must be valid JSON, and the declared GraphQL type determines how the server interprets its values. Keep boolean values as true and false, without quotes.

Selecting an effort from the schema enum alone is insufficient. The reference defines AUTO, LITE, BALANCED and MAX as effort levels, while availableReviewEfforts supplies the choices currently available to your repository. If BALANCED is missing, stop this effort-change example. Do not raise a maximum, alter an organization policy or substitute MAX to make the demonstration proceed.

Enabling customInstructionsEnabled allows reviews to use repository custom instructions; it does not create an instructions file. Disabling mcpEnabled controls whether reviews can use MCP servers. GitHub’s code review overview explains that repository MCP configuration is shared with cloud agent, while the review-specific toggle can disable MCP use for reviews. This mutation does not teach editing shared server definitions.

Verify stored settings and interpret the effective value

1. Inspect the mutation response for errors and a non-null settings object.
2. Compare the three submitted fields against the requested values.
3. Run ReadReviewSettings again using the same owner and name variables.
4. Compare the independent query with the mutation response and the saved original.

For the illustrated apply operation, the settings portion of a matching response would look like this:

{
  "availableReviewEfforts": ["LITE", "BALANCED"],
  "reviewEffort": {
    "configured": "BALANCED",
    "effective": "BALANCED"
  },
  "customInstructionsEnabled": true,
  "mcpEnabled": false,
  "severityFilter": "NO_FILTER"
}

Treat this as an expected shape and comparison target for the illustrative case. Your available efforts may differ. A response containing only part of the expected data is not a completed verification. Keep the complete response rather than extracting a reassuring boolean and discarding the surrounding error information.

Compare each field according to its role. The configured enum establishes that the explicit override was saved. The two booleans establish the requested review settings. The effective enum supplies the currently resolved default. The severity filter is a drift observation because it was deliberately absent from the write. This comparison avoids accepting a matching effective value as a substitute for the complete requested configuration.

The independent read matters because it tests the state you can retrieve after the write. It also gives you a clear point at which to detect an intervening administrator’s change. If readback differs, stop and investigate before another mutation. Repeatedly sending the desired values would obscure whether you are fighting a policy change, an availability change or another editor.

Do not request a pull request review merely to prove these settings were saved. Review execution is a different operation with different observations. GitHub’s usage guide documents manual review requests separately. A settings mutation returning the expected fields does not demonstrate that a review ran, used an instructions file or called no external tool.

Likewise, effective=BALANCED does not guarantee that every review uses Balanced. The overview places a review-request choice, prior effort on the pull request and the requester’s effort ahead of the repository default. The effective field’s own definition reflects those higher-priority choices. If a later review uses another effort, first inspect the request and pull request context instead of assuming the saved repository value disappeared.

Source: GitHub Docs, Copilot GraphQL reference. This source-page capture provides documentation context; the copyable operations above are illustrative and were not executed for this article.

Restore inheritance without freezing today’s default

1. Re-read the repository and confirm its current three-field configuration still matches the temporary change.
2. Use the saved original booleans in the recovery variables below.
3. For the confirmed inherited example, submit INHERIT rather than the saved effective LITE value.
4. Run the original query again and compare the restored configuration.

Recovery variables for task:review-settings-01:

{
  "input": {
    "repositoryId": "REPOSITORY_NODE_ID_FROM_READ",
    "reviewEffort": "INHERIT",
    "customInstructionsEnabled": false,
    "mcpEnabled": true
  }
}

Run these variables with SetReviewSettings. INHERIT is the documented RepositoryCopilotCodeReviewEffortSetting value that clears the repository’s effort so it inherits from the organization, enterprise or GitHub default. It is a mutation input, while configured=null is a possible query output. Sending the old effective value would store an explicit override and change the repository’s future relationship with upstream defaults.

After recovery, the illustrative expected configured value is null and the booleans are false and true. effective is LITE only if the inherited default and availability remain unchanged. If an administrator changes the upstream default during your exercise, restoring inheritance can correctly yield another effective effort. Compare the relationship you intended to restore as well as the displayed enum.

For an original non-null configured value, restore that saved enum instead of INHERIT, provided it remains available. If it is no longer settable, stop and report the recovery blocker rather than choosing a substitute. An exact restoration claim would be unsupported. Keep the saved response so the administrator responsible for the upstream change can see the previous configuration.

The null ambiguity deserves the same discipline. A query cannot recover an unavailable stored enum hidden behind configured=null. If your original snapshot has that ambiguity, do not promise an exact effort rollback. The useful supported route is to leave effort untouched and exercise only the two booleans. That preserves the core read-change-read-recover integration without erasing an unknown stored choice.

Illustrative mechanism: recovery clears an override rather than copying the old effective value. A null configured value requires confirmed inheritance before this effort round trip. Source: GitHub Copilot GraphQL reference, read November 7, 2026.

Use the boolean-only route when effort cannot be recovered

1. Keep the same original query and save both boolean values.
2. Submit the following variables with SetReviewSettings, leaving reviewEffort absent.
3. Re-read and verify the booleans while checking that the effort fields have not unexpectedly changed.
4. Restore the original booleans with a second mutation that also omits reviewEffort.

For the same illustrative original booleans, the complete alternative apply and recovery variable documents are:

{
  "input": {
    "repositoryId": "REPOSITORY_NODE_ID_FROM_READ",
    "customInstructionsEnabled": true,
    "mcpEnabled": false
  }
}

{
  "input": {
    "repositoryId": "REPOSITORY_NODE_ID_FROM_READ",
    "customInstructionsEnabled": false,
    "mcpEnabled": true
  }
}

These are an alternative pair, not extra mutations to append to a completed effort round trip. Choose one path before applying changes. Omission is the documented preservation behavior; explicit null is not needed here and should not be invented as a substitute for INHERIT. A client that automatically serializes every absent property as null should be configured to send the intended input document before use.

Inspect the actual outgoing variables in your existing client before submitting them. In this alternative, the input object contains the repository identifier and two booleans, with no effort property. Compare that document with the effort-changing example above. The difference is meaningful: removing a property expresses preservation, while adding INHERIT expresses clearing. A convenient form that fills every optional field would defeat the deliberate boundary of this example.

Leaving severityFilter absent follows the same principle. The read includes it so you can notice unexpected drift, but neither apply nor recovery writes it. If another administrator changes it, your recovery should not overwrite that work by replaying an entire old settings object. For broader review execution concerns, use Review Bots Now Run PR Code; this tutorial changes no runner configuration.

Diagnose a failed round trip

Observation	Interpretation and next action
Query reports missing permissions	Stop before mutation; use the error and the documented administration prerequisite to resolve access through your existing administrative process.
Repository or settings is null	Do not construct recovery inputs; check the target and accompanying errors before proceeding.
BALANCED is absent	Leave effort unchanged or use the boolean-only path; do not alter parent policy to create availability.
Apply request times out	Read settings before deciding whether to send anything again; the outcome is unknown until inspected.
Readback mismatches the submitted values	Stop additional writes and compare the complete responses, target ID and concurrent administrative changes.
Recovery restores null but effective changes	Check whether the inherited default changed; a changed resolved value can coexist with restored inheritance.

A lost mutation response is especially easy to mishandle. You have no observed result, so neither success nor failure is established. Run the read query first. If it shows the temporary configuration, you can verify or recover from that known state. If it shows a different configuration, investigate ownership of the change rather than automatically replaying either the apply or recovery request.

The same restraint applies when only one boolean differs. Do not assume the entire mutation failed, and do not use the original snapshot as permission to overwrite a colleague’s later edit. Compare the target identifier, submitted variables and retrieved state together. Establish who owns the current edit before sending recovery values. These are coordination recommendations; the documented mutation input does not provide a conditional comparison field that makes this read-and-write sequence atomic.

GitHub’s configuration guide separates these repository tuning settings from enablement, billing, maximum effort and approval controls. Do not add guessed input fields for those surfaces. Enterprise policy can constrain organization control, and maximum effort settings can restrict available levels. The repository list tells this integration what it may choose; it does not authorize overriding the hierarchy.

Keep your completed record small but concrete: the target repository and node ID, original response, exact apply variables, returned settings, independent readback, exact recovery variables and final response. Write a Finish Line the Transcript Can Prove is useful here: configuration success means matching readback and recovery, not a narrative that the request probably worked.

If you later automate this interaction across several repositories, preserve a distinct snapshot and target ID for each. Do not share one repository’s recovery values across the set. AgentOps provides the broader operating context, while Migrate Branch Protection to Rulesets covers a different governance surface. Neither replaces the per-repository state needed by this API.

The completed result is a reusable query, one typed mutation, populated apply and recovery variables, and a clear boundary around what the responses prove. Finish when the saved booleans are restored and the original explicit effort or confirmed inheritance relationship is recovered. Leave review requests, approval authority and unrelated settings to their own procedures.

Sources

1. GitHub Changelog: Copilot code review API management, November 6, 2026.
2. GitHub Docs: Copilot GraphQL reference.
3. GitHub Docs: Repositories GraphQL reference.
4. GitHub Docs: Forming calls with GraphQL.
5. GitHub Docs: Configuring code review by GitHub Copilot.
6. GitHub Docs: GitHub Copilot code review.
7. GitHub Docs: Using GitHub Copilot code review.