github-community-projects / github-community-projects/safe-settings

TeamSettings schema missing include/exclude repo filter declarations

Open
#1,011 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
921
Forks
226
Avg merge
18h 3m
Merged PRs (30d)
14

Description

## Prerequisites:

* Is the functionality available in the GitHub UI? If so, please provide a link to information about the feature.

N/A — this request is for schema validation and documentation of an existing safe-settings feature, not a new GitHub API capability.

* Is the functionality available through the GitHub API? If the functionality is available, please provide links to the API documentation (https://developer.github.com/v3/) as well as the Octokit documentation (https://octokit.github.io/).

N/A — `include`/`exclude` repo filtering is internal safe-settings logic (the `Diffable` class), not a GitHub API concept. The filtering already works at runtime for `teams` entries; it is simply not declared in the schema or covered in the documentation.

## New Feature
The `teams` section of a safe-settings configuration already supports `include` and `exclude` repo filters at runtime via the same `Diffable` logic used by `collaborators`. However, unlike `collaborators`, these keys are not declared in the `TeamSettings` JSON schema and are not documented in the teams guide.

This means:

- Editors and linters that validate configuration files against the schema report `include`/`exclude` as unknown properties on team entries, even though they are valid and functional.
- There is no official documentation or example showing users how to use per-repo filtering for teams.

Please describe the desired new functionality:

1. The `TeamSettings` definition in `schema/repos.json`, `schema/settings.json`, and `schema/suborgs.json` (and their dereferenced counterparts) should declare `include` and `exclude` using the same `allOf` pattern already used by `CollaboratorSettings`, so that editors and schema validators accept these fields without warnings.

2. The [teams guide](docs/github-settings/4.%20teams.md) should document `include` and `exclude` with descriptions and YAML examples consistent with the collaborators guide.

3. The [sample settings file](docs/sample-settings/settings.yml) should include representative team entries demonstrating both `include` and `exclude`.

4. Unit tests should cover the include/exclude filter code path for the `Teams` plugin, mirroring the coverage that exists for `Collaborators`.

No changes to runtime logic are required.

Contributor guide

Open the contributing guide

Research direction

Start by comparing the CollaboratorSettings definitions in schema/repos.json, schema/settings.json, schema/suborgs.json and their dereferenced counterparts, then read docs/github-settings/4. teams.md, docs/sample-settings/settings.yml, and the existing Collaborators tests. Done means the schemas accept team include/exclude filters, the teams guide and sample show both forms, and Teams tests cover the filter path.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, testing-qa
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.