Consistent handling of omitted config fields across plugins
Maintainers usually reply within 2 days
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- javascript
- Domain
- backend
Research direction
Start by reading the cited merge and plugin code in lib/mergeArrayBy.js, lib/plugins/environments.js, lib/plugins/diffable.js, and lib/plugins/branches.js, then compare the linked behavior in lib/mergeDeep.js. Trace how omitted, empty, and null values move through config merging and into each plugin. The issue is resolved when a consistent behavior is chosen, documented, and implemented with coverage for the listed cases; the issue does not name test files.
Written by the indexing model from the issue text.
Description
Prerequisites:
-
Is the functionality available in the GitHub UI? If so, please provide a link to information about the feature.
N/A. This is about how safe-settings interprets its own config. All settings mentioned below are already managed by safe-settings.
-
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/).
Yes. No new API is needed.
-
If the functionality is not yet available in the API, it would be helpful if you contacted support (https://support.github.com/) or posted in the Community Forum (https://github.community/). Please include a link to the forum post if you create one or a copy of the response from support.
N/A
New Feature
Plugins handle a field that is left out of the config differently. Sometimes the current value on GitHub is kept, sometimes it is reset, and sometimes the item is deleted. Should there be one documented rule, for example "an omitted field is not managed; an explicit empty value clears it"?
Current behaviour
Line references are to main-enterprise at e19444e0d69de050ba55d0262b71fcd8a98edfef.
| Feature | Field left out of the config | Code |
|---|---|---|
repository |
Unchanged. The PATCH only sends configured keys. | repository.js#L274-L281 |
branches (protection) |
Top-level fields are unchanged, because their current GitHub values are copied into the PUT body. Inside a declared block, such as required_pull_request_reviews, omitted sub-fields are dropped from the PUT, so GitHub resets them. |
branches.js#L86 |
rulesets (rule parameters) |
Treated as a deletion, unless GitHub holds the default value (#1103). | mergeDeep.js#L210-L221 |
environments |
Reset. Variables and custom protection rules are deleted, reviewers are cleared, wait_timer is set to 0, and the branch policy is removed, so all branches can deploy. |
environments.js#L101-L107 |
Diffable list plugins (e.g. variables, teams, collaborators) |
An entry that is left with only its name is dropped from the desired state. The existing item is then deleted the next time anything else in that section changes. | diffable.js#L100-L109, #L126-L127 |
Example: environments vs branch protection
Branch protection keeps top-level fields that aren't declared. This only manages admin enforcement, and the existing required reviews, status checks, restrictions and linear-history setting are kept:
branches:
- name: main
protection:
enforce_admins: true
Environments don't. This is meant to require a reviewer on prod:
environments:
- name: prod
reviewers:
- type: Team
id: 1
It also deletes every variable and custom protection rule on prod, sets wait_timer to 0, and removes the deployment branch policy. So a team can't manage its own environment variables while safe-settings manages the reviewers and branch policy. The same happens on 3.0.0 (a9a1f366ad6a738b55682d346d94f8d6c4893b09).
Interaction with org / suborg / repo config
Any rule would have to work with config merging:
- Missing key at a lower level. This already means "inherit from above", which fits "omitted = not managed".
- Explicit
[]at suborg or repo level. It is lost. Nested arrays are concatenated when entries are merged (mergeArrayBy.js#L24, which usesdeepmerge), sovariables: []in a repo file leaves the org's variables in place. For the same reason, a repo can't override an org variable's value: orgA=1plus repoA=9gives both entries. - Explicit
null. It survives the merge but is stripped before the plugin sees it (environments.js#L329-L335, diffable.js#L100-L106). For environments, a lower-leveldeployment_branch_policy: nulltherefore ends up as "omitted", which today means "reset".
Questions to consider
- Should "omitted = not managed, explicit empty or
null= clear" be the documented rule for all plugins? - If so,
nullwould need to reach the plugins instead of being stripped, so that values likedeployment_branch_policy: nullcan mean "clear". - Should an explicit
[]at a lower level replace the inherited list? - Some users rely on omission meaning "reset" (e.g. the defaults added in #649). Should the new rule be opt-in, per plugin or globally?
Environments could be a first step: make omitted fields behave like branch protection's top-level fields.
Related: #649, #1103, #1133
- Dominant language
- JavaScript
- Stars
- 942
- Forks
- 238
- PR merge metrics
- No merged PRs in 30d
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github-community-projects/safe-settings
-
Teams: teams with organization-role access show up as deletionsPossibly taken @TovaBecker claimed this 1 day ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
github-community-projects/safe-settings#1144 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
github-community-projects/safe-settings#1143 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
github-community-projects/safe-settings#1135 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
github-community-projects/safe-settings#1134 ·
Maintainers usually reply within 2 days
-
environments: additive_plugins is ignored, undeclared environments are deletedPossibly taken @yaunj claimed this 12 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
github-community-projects/safe-settings#1133 ·
Maintainers usually reply within 2 days
All issues in github-community-projects/safe-settings
Similar issues
-
area:webapp bug finding
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
humlab-sead/sead_shape_shifter#779 ·
Maintainers usually reply within 1 day
-
enhancement feature/llm-analytics
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
PostHog/posthog#139959 · 1 comment ·
Maintainers usually reply within 1 day
-
ci good first issue priority:p1
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
mobeloper/better-oss#23 ·
-
accessibility Could Have good first issue seo
Difficulty 1/5 Under an hour Newbie friendliness 88/100
hannahro15/Musical-Match-Saga#278 ·
Maintainers usually reply within 1 day