Consistent handling of omitted config fields across plugins

Open
#1,137 0 comments 0 reactions 0 assignees View on GitHub

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 uses deepmerge), so variables: [] 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: org A=1 plus repo A=9 gives 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-level deployment_branch_policy: null therefore ends up as "omitted", which today means "reset".
Questions to consider
  1. Should "omitted = not managed, explicit empty or null = clear" be the documented rule for all plugins?
  2. If so, null would need to reach the plugins instead of being stripped, so that values like deployment_branch_policy: null can mean "clear".
  3. Should an explicit [] at a lower level replace the inherited list?
  4. 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

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github-community-projects/safe-settings

All issues in github-community-projects/safe-settings

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.