[Schema Inaccuracy] Updating branch protection rules - `restrictions` schema requires subschemas of `apps` and `teams`. GitHub accounts without organizations cannot have users and teams restrictions.

[simonmcho]

Schema Inaccuracy

As title states, organization-less GitHub Accounts cannot have users and teams restrictions for branch protection rules. However, the schema for restrictions require the subschema key of teams. Passing in an empty array results in a schema error.

Expected

Schema validation to accept empty array or undefined teams subschema in restrictions.

Reproduction Steps

Scenario 1
Note the empty array for restrictions.teams:

curl \
  -X PUT \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/branches/BRANCH/protection \
  -d '{"required_status_checks":{"strict":true,"contexts":["continuous-integration/travis-ci"]},"enforce_admins":true,"required_pull_request_reviews":{"dismissal_restrictions":{"users":["octocat"],"teams":[]},"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"required_approving_review_count":2,"bypass_pull_request_allowances":{"users":["octocat"],"teams":["justice-league"]}},"restrictions":{"users":["octocat"],"teams":[],},"required_linear_history":true,"allow_force_pushes":true,"allow_deletions":true,"block_creations":true,"required_conversation_resolution":true}'

Response:

{
    "message": "Validation Failed",
    "errors": [
        "Only organization repositories can have users and team restrictions"
    ],
    "documentation_url": "https://docs.github.com/rest/reference/repos#update-branch-protection"
}

Scenario 2

Note the missing subschema for teams in restrictions:

curl \
  -X PUT \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/branches/BRANCH/protection \
  -d '{"required_status_checks":{"strict":true,"contexts":["continuous-integration/travis-ci"]},"enforce_admins":true,"required_pull_request_reviews":{"dismissal_restrictions":{"users":["octocat"],"teams":[]},"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"required_approving_review_count":2,"bypass_pull_request_allowances":{"users":["octocat"],"teams":["justice-league"]}},"restrictions":{"users":["octocat"],"teams":[],},"required_linear_history":true,"allow_force_pushes":true,"allow_deletions":true,"block_creations":true,"required_conversation_resolution":true}'

Response:

{
    "message": "Invalid request.\n\nNo subschema in \"anyOf\" matched.\nFor 'properties/users', nil is not an array.\nFor 'properties/teams', nil is not an array.\nNot all subschemas of \"allOf\" matched.\nFor 'anyOf/1', {\"users\"=>nil, \"apps\"=>[], \"teams\"=>nil} is not a null.",
    "documentation_url": "https://docs.github.com/rest/reference/repos#update-branch-protection"
}

[timrogers]

@simonmcho Thanks for flagging this! Would you be able to share the response you receive for your two reproduction steps, just so we can see what you're seeing? Once I have that, I will flag this with the relevant team at GitHub.

[timrogers]

I think I'm able to reproduce the issue - but I just want to confirm before I forward this to the team at GitHub!

My experience is that it isn't possible to set branch protection rules for a user-owned repo, because I can't find a combination of restrictions params which match the rules.

Is that what you're seeing?

Here's what I tried:

Attempt 1: null for attributes not supported for user-owned repos

Request

{
    "required_status_checks": null,
    "enforce_admins": null,
    "required_pull_request_reviews": {
        "required_approving_review_count": 1
    },
    "restrictions": {
        "users": null,
        "apps": [],
        "teams": null
    }
}

Response

{
    "message": "Invalid request.\n\nNo subschema in \"anyOf\" matched.\nFor 'properties/users', nil is not an array.\nFor 'properties/teams', nil is not an array.\nNot all subschemas of \"allOf\" matched.\nFor 'anyOf/1', {\"users\"=>nil, \"apps\"=>[], \"teams\"=>nil} is not a null.",
    "documentation_url": "https://docs.github.com/rest/reference/repos#update-branch-protection"
}

Attempt 2: [] for attributes not supported for user-owned repos

Request

{
    "required_status_checks": null,
    "enforce_admins": null,
    "required_pull_request_reviews": {
        "required_approving_review_count": 1
    },
    "restrictions": {
        "users": [],
        "apps": [],
        "teams": []
    }
}

Response

{
    "message": "Validation Failed",
    "errors": [
        "Only organization repositories can have users and team restrictions"
    ],
    "documentation_url": "https://docs.github.com/rest/reference/repos#update-branch-protection"
}

Attempt 3: Omitting attributes not supported for user-owned repos

Request

{
    "required_status_checks": null,
    "enforce_admins": null,
    "required_pull_request_reviews": {
        "required_approving_review_count": 1
    },
    "restrictions": {
        "apps": []
    }
}

Response

{
    "message": "Invalid request.\n\nNo subschema in \"anyOf\" matched.\n\"teams\", \"users\" weren't supplied.\nNot all subschemas of \"allOf\" matched.\nFor 'anyOf/1', {\"apps\"=>[]} is not a null.",
    "documentation_url": "https://docs.github.com/rest/reference/repos#update-branch-protection"
}

[simonmcho]

@timrogers Hi Tim, thanks for posting your replication of the issues and the exact responses. I am getting the same responses for each of the attempts - null, empty array, and undefined. I've updated my original posting to reflect the 2 scenarios I ran into.

My experience is that it isn't possible to set branch protection rules for a user-owned repo, because I can't find a combination of restrictions params which match the rules.

In my opinion, setting branch protection rules should not be blocked for user owned repositories just because of this schema validation.

[timrogers]

@simonmcho No worries! I've just tried this again and it does work actually if I just set restrictions to null. Does that solve your issue?

[simonmcho]

@simonmcho No worries! I've just tried this again and it does work actually if I just set restrictions to null. Does that solve your issue?

@timrogers Yes, the documentation states that setting the entire restrictions to null will disable it, thanks for that reminder! I suppose the current version of the API does not support only allowing users in the restrictions subschema? Follow-up question would be whether this request is few and far in between that there are no plans to make that a possibility for user-owned repos?

[timrogers]

I was able to set a users restriction without setting a teams restriction like this:

curl -X PUT -H "Authorization: token foo" https://api.github.com/repos/$OWNER/$REPO/branches/main/protection -d '{"enforce_admins": null, "required_status_checks": null, "required_pull_request_reviews": null, "restrictions": { "users": ["timrogers"], "teams": [] }}'

Does that make sense? I'm sure there's things we could do to make the docs on this clearer.

I'm not aware of any plans to add that functionality to user-owned repos, but it makes sense to me. I'd suggest submitting a request for that at https://github.com/github-community/community/discussions/categories/general.

[simonmcho]

Thank you. We can consider this issue closed for now, I can take a further look in terms of doc clarification or feature request.