Skip to content

docs(branching): define Dependabot security-update exception for main guards #487

Description

@ss-o

Goal

Reconcile the ADR-0008 next promotion guard with ADR-0012's Dependabot
security-update ownership so a required main-branch source check does not block
GitHub's supported security-update path.

Verified conflict (2026-07-28)

  • runbooks/branch-protection.md currently describes a source guard that
    accepts only same-repository next and hotfix-* pull requests into main.
  • GitHub documents that Dependabot target-branch routes version updates only;
    Dependabot security updates still target the repository's default branch.
  • GitHub's default Dependabot branch names use dependabot/..., and Dependabot
    pull requests are authored by the Dependabot bot account.
  • In z-shell/zsh-lint, routine Dependabot updates are being routed to next
    while the default branch remains main. Requiring the current guard pattern
    unchanged would therefore block a normal Dependabot security-update pull
    request into main.
  • A workflow can check the same-repository head, dependabot/* prefix, and
    immutable pull-request author. Those signals authenticate a Dependabot pull
    request but do not prove that it is a security update. A routine Dependabot
    pull request manually retargeted by a maintainer is the main limitation of
    that exception.

Decision needed

Choose and document one organization-wide control:

  1. Allow authenticated same-repository Dependabot pull requests through the
    main source guard, documenting the retargeting limitation.
  2. Require maintainers to convert every Dependabot security update into a
    reviewed hotfix-* path.
  3. Use a stronger GitHub-native ruleset or bypass mechanism that preserves
    security-update automation without broadly accepting bot-authored branches.

Acceptance criteria

  • ADR-0008, ADR-0012, and the branch-protection runbook describe one compatible
    policy for Dependabot security updates.
  • The canonical guard pattern and tests match the chosen policy.
  • Routine version updates still target next.
  • Dependabot security updates can reach main through an explicit, reviewed
    path.
  • Any provenance or maintainer-retargeting limitation is stated rather than
    implied away.

References

  • z-shell/zsh-lint#98
  • decisions/0008-branching-model.md
  • decisions/0012-hybrid-dependency-management.md
  • runbooks/branch-protection.md
  • GitHub Docs: Dependabot pull requests
  • GitHub Docs: Dependabot options reference (target-branch)

This issue records the policy correction only. No organization policy file is
being edited as part of the zsh-lint Phase 1 implementation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions