feat: add GOTRUE_DB_DEFAULT_ROLE with backward compatibility and tests

[nancysangani]

What kind of change does this PR introduce?

Feature (with backward compatibility)

What is the current behavior?

The default role for newly created users is derived from GOTRUE_JWT_DEFAULT_GROUP_NAME, which is being deprecated. This couples user role assignment with JWT configuration and limits flexibility.

Fixes #2359

What is the new behavior?

• Introduces a new environment variable: GOTRUE_DB_DEFAULT_ROLE
• This value is used as the default role for newly created users
• Backward compatibility is preserved:
  • If GOTRUE_DB_DEFAULT_ROLE is set → it is used
  • Else if GOTRUE_JWT_DEFAULT_GROUP_NAME is set → fallback to it
  • Else → defaults to "authenticated"
• Adds a deprecation warning for GOTRUE_JWT_DEFAULT_GROUP_NAME

Additional context

• Updates user creation logic to use DB.DefaultRole
• Updates example.env to include the new variable
• Keeps existing behavior unchanged unless the new variable is used

Tests

• Added TestDefaultRoleApplyDefaults to verify:

  • Custom role usage
  • Default fallback behavior
  • Backward compatibility
  • Precedence rules

• Verified locally using:

  go test ./internal/conf -v

[nancysangani]

/cc @cstockton
/cc @staaldraad
/cc @fadymak

[Copilot]

Pull request overview

This PR decouples “new user default role” from JWT configuration by introducing GOTRUE_DB_DEFAULT_ROLE (with a backward-compatible fallback to GOTRUE_JWT_DEFAULT_GROUP_NAME) and updates user creation paths to use the DB-configured default role.

Changes:

• Add DB.DefaultRole to configuration and defaulting logic (fallback to legacy JWT default group name, then "authenticated").
• Use config.DB.DefaultRole when assigning roles during user signup and admin user creation.
• Add a deprecation notice for GOTRUE_JWT_DEFAULT_GROUP_NAME and tests covering precedence/fallback behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/conf/configuration.go	Adds DB.DefaultRole and sets default role with legacy fallback in ApplyDefaults().
internal/conf/configuration_test.go	Adds tests validating default role precedence and backward compatibility.
internal/api/signup.go	Assigns new users the role from config.DB.DefaultRole.
internal/api/admin.go	Uses config.DB.DefaultRole as the default role for admin-created users (unless overridden).
internal/api/api.go	Updates deprecation warning text for GOTRUE_JWT_DEFAULT_GROUP_NAME.
example.env	Documents the new env var and adds GOTRUE_DB_DEFAULT_ROLE.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

example.env now documents GOTRUE_DB_DEFAULT_ROLE but still sets GOTRUE_JWT_DEFAULT_GROUP_NAME. Because the old variable is deprecated (and triggers a startup warning), consider removing it from the example, or at least commenting it out / adding an explicit deprecation note so users don’t copy a deprecated setting by default.

[cstockton]

Please see https://github.com/supabase/auth/blob/master/CONTRIBUTING.md

[nancysangani]

@cstockton Thanks for pointing me to the contributing guidelines!

I’m a bit unsure how to proceed with this change. Since it introduces a new env variable, I understand it may be considered a feature and require an RFC — but the RFC repository appears to be read-only.

Could you please clarify what you’d prefer here:

• Should I open/design an RFC somewhere else, or
• Should I rework this as a smaller bug fix without introducing a new configuration option?

I’m happy to adjust the approach accordingly — just want to align with the expected contribution process.

[cstockton]

@nancysangani I would start by opening issues to discuss if these features will be accepted by the team. Some of them would require platform changes on our side that we might not be willing to commit to.