fix(admin): offer --purge for users who own repositories and show roles

admin user delete of a user who owns repositories failed with Gitea's raw
HTTP 422. The error now says what blocks the deletion and how to proceed,
and --purge deletes the account with its repositories, packages and
organization memberships after typing the username on a terminal.

admin user list shows ROLE and STATUS columns (admin, restricted, user;
active, inactive, login prohibited) with the email and creation date
instead of admin=true/active=true cells, and --query filters by username,
name or email. admin user view shows the account instead of its list
row. create asks for a missing username and email address with readable
labels and re-asks for invalid answers, mutations print ✓ lines, usernames
complete, and every command has examples.

Signed-off-by: bircni <bircni@icloud.com>
This commit is contained in:
bircni committed 2026-10-11 23:42:49 +02:00
1 parent ef8cfbc4b7
commit c18dae6685
6 files changed
+465 -195

No files matched your search

+353 -172
View File
@@ -4,7 +4,9 @@
package app
import (
"context"
"errors"
"fmt"
"net/mail"
"strconv"
"strings"
@@ -16,191 +18,370 @@ import (
)
func (a *application) adminCommand() *cobra.Command {
group := &cobra.Command{Use: "admin", Short: "Manage instance administration"}
users := &cobra.Command{Use: "user", Short: "Manage registered accounts"}
group := &cobra.Command{Use: "admin", Short: "Manage instance administration", Long: "Administer the Gitea instance. These commands need an administrator account."}
users := &cobra.Command{Use: "user", Short: "Manage registered accounts", Long: `List, view, create, edit and delete the accounts of the instance. These commands need an
administrator account.`}
users.AddCommand(a.adminUserListCommand(), a.adminUserViewCommand())
for _, verb := range []string{"create", "edit"} {
users.AddCommand(a.adminUserChangeCommand(verb))
}
users.AddCommand(a.adminUserDeleteCommand())
group.AddCommand(users)
var limit, page int
list := &cobra.Command{Use: "list", Short: "List registered accounts", Args: argsExact(0), RunE: func(cmd *cobra.Command, _ []string) error {
target, err := a.resolve(cmd.Context(), false)
if err != nil {
return err
}
items, err := (services.AdminUsers{Client: target.client}).List(cmd.Context(), limit, page)
if err != nil {
return err
}
return writeList(a, cmd, items, adminUserRow)
}}
pageFlags(list, &limit, &page)
users.AddCommand(list)
for _, verb := range []string{"view", "create", "edit", "delete"} {
var username, email, fullName, description, website, location, visibility, password, passwordFile string
var admin, active, restricted, prohibitLogin, mustChangePassword, allowGitHook, allowImportLocal, allowCreateOrganization bool
var maxRepos int
opts := services.AdminUserOptions{}
command := &cobra.Command{Use: verb + " <username>", Short: titleCase(verb) + " an account", Args: argsExact(1)}
if verb == "create" {
command.Use = "create [username]"
command.Args = usageArgs(cobra.MaximumNArgs(1))
command.Flags().StringVar(&username, "username", "", "Account username")
}
if verb == "delete" {
command.Annotations = textOutput("account deletion does not return a resource")
}
type stringBinding struct {
name, description string
value *string
option **string
}
stringsToBind := []stringBinding{{"email", "Email address", &email, &opts.Email}, {"full-name", "Display name", &fullName, &opts.FullName}, {"visibility", "Profile visibility: public, limited, private", &visibility, &opts.Visibility}}
type boolBinding struct {
name, description string
value *bool
option **bool
}
boolsToBind := []boolBinding{{"admin", "Administrator privileges", &admin, &opts.Admin}, {"restricted", "Restrict account access", &restricted, &opts.Restricted}, {"prohibit-login", "Prohibit signing in", &prohibitLogin, &opts.ProhibitLogin}}
if verb == "edit" {
stringsToBind = append(stringsToBind, stringBinding{"description", "Profile description", &description, &opts.Description}, stringBinding{"website", "Website URL", &website, &opts.Website}, stringBinding{"location", "Location", &location, &opts.Location})
boolsToBind = append(boolsToBind, boolBinding{"active", "Activate account", &active, &opts.Active}, boolBinding{"allow-git-hook", "Allow Git hooks", &allowGitHook, &opts.AllowGitHook}, boolBinding{"allow-import-local", "Allow local repository imports", &allowImportLocal, &opts.AllowImportLocal}, boolBinding{"allow-create-organization", "Allow creating organizations", &allowCreateOrganization, &opts.AllowCreateOrganization})
command.Flags().IntVar(&maxRepos, "max-repo-creation", 0, "Repository creation limit (-1 for unlimited)")
}
if verb == "create" || verb == "edit" {
for _, binding := range stringsToBind {
command.Flags().StringVar(binding.value, binding.name, "", binding.description)
}
for _, binding := range boolsToBind {
command.Flags().BoolVar(binding.value, binding.name, false, binding.description+" (use =false to revoke)")
}
command.Flags().StringVar(&password, "password", "", "Password (prefer --password-file)")
command.Flags().StringVar(&passwordFile, "password-file", "", "Read password from file or - for stdin; remove one trailing line ending")
command.Flags().BoolVar(&mustChangePassword, "must-change-password", verb == "create", "Require password change on next sign-in (use =false to disable)")
}
command.RunE = func(cmd *cobra.Command, args []string) error {
if verb == "create" {
if len(args) > 0 {
if cmd.Flags().Changed("username") {
return clierr.Wrap(clierr.Usage, errors.New("supply username as an argument or --username, not both"))
}
username = args[0]
}
for _, field := range []struct {
value *string
flag string
}{{&username, "username"}, {&email, "email"}} {
if _, err := a.require(cmd, field.value, field.flag); err != nil {
return err
}
}
opts.Email = &email
opts.FullName = &fullName
if visibility == "" {
visibility = "public"
}
opts.Visibility = &visibility
} else {
username = args[0]
}
if strings.TrimSpace(username) == "" || strings.ContainsAny(username, "/\\ \t\r\n") {
return clierr.Wrap(clierr.Usage, errors.New("invalid account username"))
}
if verb == "create" || verb == "edit" {
for _, binding := range stringsToBind {
if cmd.Flags().Changed(binding.name) {
*binding.option = binding.value
}
}
for _, binding := range boolsToBind {
if cmd.Flags().Changed(binding.name) {
*binding.option = binding.value
}
}
if opts.Email != nil {
address, err := mail.ParseAddress(email)
if err != nil || address.Address != email {
return clierr.Wrap(clierr.Usage, errors.New("--email must contain one email address"))
}
}
if opts.Visibility != nil {
if err := oneOf("visibility", visibility, "public", "limited", "private"); err != nil {
return err
}
}
if cmd.Flags().Changed("max-repo-creation") {
if maxRepos < -1 {
return clierr.Wrap(clierr.Usage, errors.New("--max-repo-creation must be -1 or nonnegative"))
}
opts.MaxRepoCreation = &maxRepos
}
passwordChange := verb == "create" || cmd.Flags().Changed("password") || cmd.Flags().Changed("password-file")
if passwordChange {
var err error
if password, err = a.readSecret(cmd, password, passwordFile, "password", "password-file"); err != nil {
return err
}
if password == "" && !cmd.Flags().Changed("password-file") {
snapshot, err := a.deps.Settings.Load()
if err != nil {
return err
}
if !a.policy(snapshot).CanPrompt(a.deps.Streams) {
return clierr.Wrap(clierr.Usage, errors.New("missing password: supply --password-file or --password"))
}
password, err = a.deps.Prompter.SecretInput(cmd.Context(), "Password for "+username)
if err != nil {
return err
}
confirmation, err := a.deps.Prompter.SecretInput(cmd.Context(), "Confirm password")
if err != nil {
return err
}
if password != confirmation {
return clierr.Wrap(clierr.Usage, errors.New("passwords do not match"))
}
}
if password == "" {
return clierr.Wrap(clierr.Usage, errors.New("password cannot be empty"))
}
opts.Password = password
}
if verb == "create" || cmd.Flags().Changed("must-change-password") {
opts.MustChangePassword = &mustChangePassword
}
return group
}
if verb == "edit" && opts == (services.AdminUserOptions{}) {
return clierr.Wrap(clierr.Usage, errors.New("supply account fields to edit"))
}
// completeAdminUsers completes the usernames of the instance with their names.
func (a *application) completeAdminUsers() cobra.CompletionFunc {
return a.apiCompletion(false, func(ctx context.Context, t target, toComplete string) ([]cobra.Completion, error) {
users, err := (services.AdminUsers{Client: t.client}).List(ctx, toComplete, completionLimit, 1)
return describe(users.Items, func(user services.AdminUser) (string, string) { return user.Username, user.FullName }), err
})
}
// userRole is admin, restricted or user.
func userRole(user services.AdminUser) terminal.Cell {
switch {
case user.Admin:
return terminal.Cell{Text: "admin", Color: "magenta"}
case user.Restricted:
return terminal.Cell{Text: "restricted", Color: "yellow"}
}
return terminal.Cell{Text: "user"}
}
// userStatus is active, inactive or login prohibited.
func userStatus(user services.AdminUser) terminal.Cell {
switch {
case user.ProhibitLogin:
return terminal.Cell{Text: "login prohibited", Color: "red"}
case !user.Active:
return terminal.Cell{Text: "inactive", Color: "yellow"}
}
return terminal.Cell{Text: "active", Color: "green"}
}
func (a *application) adminUserListCommand() *cobra.Command {
var query string
var limit, page int
cmd := &cobra.Command{
Use: "list", Short: "List registered accounts", Args: argsExact(0),
Example: `$ tea admin user list
# find accounts by username, name or email
$ tea admin user list --query bob
# print the email addresses
$ tea admin user list --jq '.[].email'`,
RunE: func(cmd *cobra.Command, _ []string) error {
target, err := a.resolve(cmd.Context(), false)
if err != nil {
return err
}
users, err := (services.AdminUsers{Client: target.client}).List(cmd.Context(), query, limit, page)
if err != nil {
return err
}
spec := listSpec[services.AdminUser]{
Columns: []terminal.Column{{Header: "ID"}, {Header: "Username"}, {Header: "Name", Flex: true}, {Header: "Email"}, {Header: "Role"}, {Header: "Status"}, {Header: "Created"}},
Row: func(user services.AdminUser) []terminal.Cell {
return []terminal.Cell{
{Text: strconv.FormatInt(user.ID, 10), Link: user.URL},
{Text: user.Username, Bold: true},
{Text: user.FullName},
{Text: user.Email},
userRole(user), userStatus(user),
{Time: terminal.ParseTime(user.CreatedAt)},
}
},
Context: "users on " + target.Host, Empty: "no users on " + target.Host,
}
if query != "" {
spec.Context, spec.Empty = fmt.Sprintf("users matching %q", query), fmt.Sprintf("no users match %q", query)
}
return writeTable(a, cmd, users.Items, spec, servicePage(users, page))
},
}
cmd.Flags().StringVar(&query, "query", "", "Only list accounts whose username, name or email contains this text")
pageFlags(cmd, &limit, &page)
return cmd
}
func (a *application) adminUserViewCommand() *cobra.Command {
return &cobra.Command{
Use: "view <username>", Short: "View an account", Args: argsExact(1), ValidArgsFunction: a.completeAdminUsers(),
Example: `$ tea admin user view bob
$ tea admin user view bob --json email,admin`,
RunE: func(cmd *cobra.Command, args []string) error {
if err := validUsername(args[0]); err != nil {
return clierr.Wrap(clierr.Usage, err)
}
target, err := a.resolve(cmd.Context(), false)
if err != nil {
return err
}
if verb == "delete" {
if err := a.confirm(cmd, verb+" account "+username+" on "+target.Host); err != nil {
return err
user, err := (services.AdminUsers{Client: target.client}).View(cmd.Context(), args[0])
if err != nil {
return err
}
d := a.display()
return writeView(a, cmd, user, func(user services.AdminUser) terminal.View {
created := timeField("Created", user.CreatedAt, d)
meta := ""
if created.Value != "" {
meta = "joined " + created.Value
}
role, status := userRole(user), userStatus(user)
created.PipedOnly = true
return terminal.View{
Title: user.Username, ID: fmt.Sprintf("(ID %d)", user.ID), Badges: []terminal.Cell{role, status}, Meta: meta,
Fields: []terminal.Field{
{Label: "Name", Value: user.FullName},
{Label: "Email", Value: user.Email},
{Label: "Role", Value: role.Text, PipedOnly: true},
{Label: "Status", Value: status.Text, PipedOnly: true},
{Label: "Visibility", Value: user.Visibility},
{Label: "Website", Value: user.Website},
{Label: "Location", Value: user.Location},
created,
},
Body: user.Description, Kind: "user", URL: user.URL,
}
})
},
}
}
// adminUserChangeCommand creates or edits an account.
func (a *application) adminUserChangeCommand(verb string) *cobra.Command {
var username, email, fullName, description, website, location, visibility, password, passwordFile string
var admin, active, restricted, prohibitLogin, mustChangePassword, allowGitHook, allowImportLocal, allowCreateOrganization bool
var maxRepos int
opts := services.AdminUserOptions{}
command := &cobra.Command{
Use: "edit <username>", Short: "Edit an account", Args: argsExact(1), ValidArgsFunction: a.completeAdminUsers(),
Example: `$ tea admin user edit bob --full-name "Bob Builder" --restricted
# reset a password and require a new one on the next sign-in
$ tea admin user edit bob --password-file pw.txt --must-change-password
# revoke administrator privileges
$ tea admin user edit bob --admin=false`,
}
if verb == "create" {
command.Use, command.Short, command.ValidArgsFunction = "create [<username>]", "Create an account", nil
command.Args = usageArgs(cobra.MaximumNArgs(1))
command.Long = `Create an account. On a terminal, tea asks for a missing username, email address and
password; the new account must change its password on its first sign-in unless
--must-change-password=false is passed.`
command.Example = `$ tea admin user create carol --email carol@example.com
# read the password from a file instead of a prompt
$ tea admin user create ci-bot --email ci@example.com --password-file pw.txt --must-change-password=false`
command.Flags().StringVar(&username, "username", "", "Account username")
}
type stringBinding struct {
name, description string
value *string
option **string
}
stringsToBind := []stringBinding{{"email", "Email address", &email, &opts.Email}, {"full-name", "Display name", &fullName, &opts.FullName}}
type boolBinding struct {
name, description string
value *bool
option **bool
}
boolsToBind := []boolBinding{{"admin", "Administrator privileges", &admin, &opts.Admin}, {"restricted", "Restrict account access", &restricted, &opts.Restricted}, {"prohibit-login", "Prohibit signing in", &prohibitLogin, &opts.ProhibitLogin}}
if verb == "edit" {
stringsToBind = append(stringsToBind, stringBinding{"description", "Profile description", &description, &opts.Description}, stringBinding{"website", "Website URL", &website, &opts.Website}, stringBinding{"location", "Location", &location, &opts.Location})
boolsToBind = append(boolsToBind, boolBinding{"active", "Activate account", &active, &opts.Active}, boolBinding{"allow-git-hook", "Allow Git hooks", &allowGitHook, &opts.AllowGitHook}, boolBinding{"allow-import-local", "Allow local repository imports", &allowImportLocal, &opts.AllowImportLocal}, boolBinding{"allow-create-organization", "Allow creating organizations", &allowCreateOrganization, &opts.AllowCreateOrganization})
command.Flags().IntVar(&maxRepos, "max-repo-creation", 0, "Repository creation limit (-1 for unlimited)")
}
for _, binding := range stringsToBind {
command.Flags().StringVar(binding.value, binding.name, "", binding.description)
}
initialVisibility := ""
if verb == "create" {
initialVisibility = "public"
}
enumFlag(command, &visibility, "visibility", "", initialVisibility, "Profile visibility", visibilities...)
for _, binding := range boolsToBind {
command.Flags().BoolVar(binding.value, binding.name, false, binding.description+" (use =false to revoke)")
}
command.Flags().StringVar(&password, "password", "", "Password (prefer --password-file)")
command.Flags().StringVar(&passwordFile, "password-file", "", "Read password from file or - for stdin; remove one trailing line ending")
command.Flags().BoolVar(&mustChangePassword, "must-change-password", verb == "create", "Require password change on next sign-in (use =false to disable)")
command.RunE = func(cmd *cobra.Command, args []string) error {
if verb == "create" {
if len(args) > 0 {
if cmd.Flags().Changed("username") {
return clierr.Wrap(clierr.Usage, errors.New("supply username as an argument or --username, not both"))
}
username = args[0]
}
if _, err := a.requireInput(cmd, &username, "username", "Username", validUsername); err != nil {
return err
}
if _, err := a.requireInput(cmd, &email, "email", "Email address", validEmail); err != nil {
return err
}
opts.Email, opts.FullName, opts.Visibility = &email, &fullName, &visibility
} else {
username = args[0]
}
if err := validUsername(username); err != nil {
return clierr.Wrap(clierr.Usage, err)
}
for _, binding := range stringsToBind {
if cmd.Flags().Changed(binding.name) {
*binding.option = binding.value
}
}
if cmd.Flags().Changed("visibility") {
opts.Visibility = &visibility
}
for _, binding := range boolsToBind {
if cmd.Flags().Changed(binding.name) {
*binding.option = binding.value
}
}
if opts.Email != nil {
if err := validEmail(email); err != nil {
return clierr.Wrap(clierr.Usage, fmt.Errorf("--email: %w", err))
}
}
if cmd.Flags().Changed("max-repo-creation") {
if maxRepos < -1 {
return clierr.Wrap(clierr.Usage, errors.New("--max-repo-creation must be -1 or nonnegative"))
}
opts.MaxRepoCreation = &maxRepos
}
if verb == "create" || cmd.Flags().Changed("password") || cmd.Flags().Changed("password-file") {
var err error
if opts.Password, err = a.adminUserPassword(cmd, username, password, passwordFile); err != nil {
return err
}
}
if verb == "create" || cmd.Flags().Changed("must-change-password") {
opts.MustChangePassword = &mustChangePassword
}
if verb == "edit" && opts == (services.AdminUserOptions{}) {
return clierr.Wrap(clierr.Usage, errors.New("supply account fields to edit"))
}
target, err := a.resolve(cmd.Context(), false)
if err != nil {
return err
}
service := services.AdminUsers{Client: target.client}
if verb == "edit" {
user, err := service.Edit(cmd.Context(), username, opts)
if err != nil {
return err
}
a.done(cmd, "Edited user %s", user.Username)
return a.jsonResult(cmd, user)
}
user, err := service.Create(cmd.Context(), username, opts)
if err != nil {
return err
}
a.done(cmd, "Created user %s", user.Username)
if err := a.printURL(cmd, user.URL); err != nil {
return err
}
return a.jsonResult(cmd, user)
}
return command
}
// adminUserPassword reads the password from its flags, or asks twice on a terminal.
func (a *application) adminUserPassword(cmd *cobra.Command, username, password, passwordFile string) (string, error) {
password, err := a.readSecret(cmd, password, passwordFile, "password", "password-file")
if err != nil {
return "", err
}
if password == "" && !cmd.Flags().Changed("password-file") {
snapshot, err := a.deps.Settings.Load()
if err != nil {
return "", err
}
if !a.policy(snapshot).CanPrompt(a.deps.Streams) {
return "", clierr.Wrap(clierr.Usage, errors.New("missing password: supply --password-file or --password"))
}
if password, err = a.deps.Prompter.SecretInput(cmd.Context(), "Password for "+username); err != nil {
return "", err
}
confirmation, err := a.deps.Prompter.SecretInput(cmd.Context(), "Confirm password")
if err != nil {
return "", err
}
if password != confirmation {
return "", clierr.Wrap(clierr.Usage, errors.New("passwords do not match"))
}
}
if password == "" {
return "", clierr.Wrap(clierr.Usage, errors.New("password cannot be empty"))
}
return password, nil
}
func validUsername(username string) error {
if strings.TrimSpace(username) == "" || strings.ContainsAny(username, "/\\ \t\r\n") {
return errors.New("invalid account username")
}
return nil
}
func validEmail(email string) error {
if address, err := mail.ParseAddress(email); err != nil || address.Address != email {
return errors.New("enter one email address, such as carol@example.com")
}
return nil
}
func (a *application) adminUserDeleteCommand() *cobra.Command {
var purge bool
cmd := &cobra.Command{
Use: "delete <username>", Short: "Delete an account", Args: argsExact(1), ValidArgsFunction: a.completeAdminUsers(),
Long: `Delete an account. Gitea refuses while the user owns repositories or is the last owner of an
organization: transfer or delete those first, or pass --purge to delete the account with
everything it owns. A purge cannot be undone, so a terminal asks you to type the username.`,
Example: `$ tea admin user delete spammer
# also delete the user's repositories, packages and organization memberships
$ tea admin user delete spammer --purge`,
Annotations: map[string]string{"tea.text": "account deletion does not return a resource", "tea.confirm": "true"},
RunE: func(cmd *cobra.Command, args []string) error {
if err := validUsername(args[0]); err != nil {
return clierr.Wrap(clierr.Usage, err)
}
target, err := a.resolve(cmd.Context(), false)
if err != nil {
return err
}
service := services.AdminUsers{Client: target.client}
var item services.AdminUser
switch verb {
case "view":
item, err = service.View(cmd.Context(), username)
case "create":
item, err = service.Create(cmd.Context(), username, opts)
case "edit":
item, err = service.Edit(cmd.Context(), username, opts)
case "delete":
return service.Delete(cmd.Context(), username)
user, err := service.View(cmd.Context(), args[0])
if err != nil {
return err
}
confirmation := terminal.Confirmation{Prompt: fmt.Sprintf("Delete user %s?", user.Username), NonTTY: "delete user " + user.Username}
if purge {
confirmation = terminal.Confirmation{
Prompt: fmt.Sprintf("Delete user %s with their repositories, packages and organization memberships? This cannot be undone.", user.Username),
Typed: user.Username, NonTTY: "purge user " + user.Username,
}
}
if err := a.confirmAction(cmd, confirmation); err != nil {
return err
}
err = service.Delete(cmd.Context(), user.Username, purge)
if conflict, ok := errors.AsType[*services.ConflictError](err); ok && conflict.Reason == services.ReasonOwnsRepos {
conflict.Hint = "transfer or delete them, or pass --purge to delete them with the user"
}
if err != nil {
return err
}
return writeItem(a, cmd, item, adminUserRow)
}
users.AddCommand(command)
if purge {
a.done(cmd, "Deleted user %s and everything they owned", user.Username)
} else {
a.done(cmd, "Deleted user %s", user.Username)
}
return nil
},
}
return group
}
func adminUserRow(item services.AdminUser) []terminal.Cell {
return terminal.Row(strconv.FormatInt(item.ID, 10), item.Username, item.FullName, "admin="+strconv.FormatBool(item.Admin), "active="+strconv.FormatBool(item.Active))
cmd.Flags().BoolVar(&purge, "purge", false, "Also delete the user's repositories, packages and organization memberships")
return cmd
}