coder · hugodutka · Mar 21, 2025 · Mar 20, 2025 · Mar 20, 2025 · Mar 20, 2025
diff --git a/cli/testdata/coder_users_list_--help.golden b/cli/testdata/coder_users_list_--help.golden
@@ -9,6 +9,9 @@ OPTIONS:
   -c, --column [id|username|email|created at|updated at|status] (default: username,email,created at,status)
           Columns to display in table output.
 
+      --github-user-id int
+          Filter users by their GitHub user ID.
+
   -o, --output table|json (default: table)
           Output format.
 

diff --git a/cli/userlist.go b/cli/userlist.go
@@ -19,6 +19,7 @@ func (r *RootCmd) userList() *serpent.Command {
 		cliui.JSONFormat(),
 	)
 	client := new(codersdk.Client)
+	var githubUserID int64
 
 	cmd := &serpent.Command{
 		Use:     "list",
@@ -27,8 +28,23 @@ func (r *RootCmd) userList() *serpent.Command {
 			serpent.RequireNArgs(0),
 			r.InitClient(client),
 		),
+		Options: serpent.OptionSet{
+			{
+				Name:        "github-user-id",
+				Description: "Filter users by their GitHub user ID.",
+				Default:     "",
+				Flag:        "github-user-id",
+				Required:    false,
+				Value:       serpent.Int64Of(&githubUserID),
+			},
+		},
 		Handler: func(inv *serpent.Invocation) error {
-			res, err := client.Users(inv.Context(), codersdk.UsersRequest{})
+			req := codersdk.UsersRequest{}
+			if githubUserID != 0 {
+				req.Search = fmt.Sprintf("github_com_user_id:%d", githubUserID)
+			}
+
+			res, err := client.Users(inv.Context(), req)
 			if err != nil {
 				return err
 			}

diff --git a/coderd/database/dbmem/dbmem.go b/coderd/database/dbmem/dbmem.go
@@ -6577,6 +6577,16 @@ func (q *FakeQuerier) GetUsers(_ context.Context, params database.GetUsersParams
 		users = usersFilteredByLastSeen
 	}
 
+	if params.GithubComUserID != 0 {
+		usersFilteredByGithubComUserID := make([]database.User, 0, len(users))
+		for i, user := range users {
+			if user.GithubComUserID.Int64 == params.GithubComUserID {
+				usersFilteredByGithubComUserID = append(usersFilteredByGithubComUserID, users[i])
+			}
+		}
+		users = usersFilteredByGithubComUserID
+	}
+
 	beforePageCount := len(users)
 
 	if params.OffsetOpt > 0 {

diff --git a/coderd/database/modelqueries.go b/coderd/database/modelqueries.go
@@ -393,6 +393,7 @@ func (q *sqlQuerier) GetAuthorizedUsers(ctx context.Context, arg GetUsersParams,
 		arg.LastSeenAfter,
 		arg.CreatedBefore,
 		arg.CreatedAfter,
+		arg.GithubComUserID,
 		arg.OffsetOpt,
 		arg.LimitOpt,
 	)

diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/users.sql b/coderd/database/queries/users.sql
@@ -223,6 +223,11 @@ WHERE
 			created_at >= @created_after
 		ELSE true
 	END
+	AND CASE
+		WHEN @github_com_user_id :: bigint != 0 THEN
+			github_com_user_id = @github_com_user_id
+		ELSE true
+	END
 	-- End of filters
 
 	-- Authorize Filter clause will be injected below in GetAuthorizedUsers

diff --git a/coderd/httpapi/queryparams.go b/coderd/httpapi/queryparams.go
@@ -82,6 +82,20 @@ func (p *QueryParamParser) Int(vals url.Values, def int, queryParam string) int
 	return v
 }
 
+func (p *QueryParamParser) Int64(vals url.Values, def int64, queryParam string) int64 {
+	v, err := parseQueryParam(p, vals, func(v string) (int64, error) {
+		return strconv.ParseInt(v, 10, 64)
+	}, def, queryParam)
+	if err != nil {
+		p.Errors = append(p.Errors, codersdk.ValidationError{
+			Field:  queryParam,
+			Detail: fmt.Sprintf("Query param %q must be a valid 64-bit integer: %s", queryParam, err.Error()),
+		})
+		return 0
+	}
+	return v
+}
+
 // PositiveInt32 function checks if the given value is 32-bit and positive.
 //
 // We can't use `uint32` as the value must be within the range  <0,2147483647>

diff --git a/coderd/searchquery/search.go b/coderd/searchquery/search.go
@@ -80,13 +80,14 @@ func Users(query string) (database.GetUsersParams, []codersdk.ValidationError) {
 
 	parser := httpapi.NewQueryParamParser()
 	filter := database.GetUsersParams{
-		Search:         parser.String(values, "", "search"),
-		Status:         httpapi.ParseCustomList(parser, values, []database.UserStatus{}, "status", httpapi.ParseEnum[database.UserStatus]),
-		RbacRole:       parser.Strings(values, []string{}, "role"),
-		LastSeenAfter:  parser.Time3339Nano(values, time.Time{}, "last_seen_after"),
-		LastSeenBefore: parser.Time3339Nano(values, time.Time{}, "last_seen_before"),
-		CreatedAfter:   parser.Time3339Nano(values, time.Time{}, "created_after"),
-		CreatedBefore:  parser.Time3339Nano(values, time.Time{}, "created_before"),
+		Search:          parser.String(values, "", "search"),
+		Status:          httpapi.ParseCustomList(parser, values, []database.UserStatus{}, "status", httpapi.ParseEnum[database.UserStatus]),
+		RbacRole:        parser.Strings(values, []string{}, "role"),
+		LastSeenAfter:   parser.Time3339Nano(values, time.Time{}, "last_seen_after"),
+		LastSeenBefore:  parser.Time3339Nano(values, time.Time{}, "last_seen_before"),
+		CreatedAfter:    parser.Time3339Nano(values, time.Time{}, "created_after"),
+		CreatedBefore:   parser.Time3339Nano(values, time.Time{}, "created_before"),
+		GithubComUserID: parser.Int64(values, 0, "github_com_user_id"),
 	}
 	parser.ErrorExcessParams(values)
 	return filter, parser.Errors

diff --git a/coderd/users.go b/coderd/users.go
@@ -297,16 +297,17 @@ func (api *API) GetUsers(rw http.ResponseWriter, r *http.Request) ([]database.Us
 	}
 
 	userRows, err := api.Database.GetUsers(ctx, database.GetUsersParams{
-		AfterID:        paginationParams.AfterID,
-		Search:         params.Search,
-		Status:         params.Status,
-		RbacRole:       params.RbacRole,
-		LastSeenBefore: params.LastSeenBefore,
-		LastSeenAfter:  params.LastSeenAfter,
-		CreatedAfter:   params.CreatedAfter,
-		CreatedBefore:  params.CreatedBefore,
-		OffsetOpt:      int32(paginationParams.Offset),
-		LimitOpt:       int32(paginationParams.Limit),
+		AfterID:         paginationParams.AfterID,
+		Search:          params.Search,
+		Status:          params.Status,
+		RbacRole:        params.RbacRole,
+		LastSeenBefore:  params.LastSeenBefore,
+		LastSeenAfter:   params.LastSeenAfter,
+		CreatedAfter:    params.CreatedAfter,
+		CreatedBefore:   params.CreatedBefore,
+		GithubComUserID: params.GithubComUserID,
+		OffsetOpt:       int32(paginationParams.Offset),
+		LimitOpt:        int32(paginationParams.Limit),
 	})
 	if err != nil {
 		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{

diff --git a/coderd/users_test.go b/coderd/users_test.go
@@ -2,6 +2,7 @@ package coderd_test
 
 import (
 	"context"
+	"database/sql"
 	"fmt"
 	"net/http"
 	"slices"
@@ -1873,6 +1874,33 @@ func TestGetUsers(t *testing.T) {
 		require.NoError(t, err)
 		require.ElementsMatch(t, active, res.Users)
 	})
+	t.Run("GithubComUserID", func(t *testing.T) {
+		t.Parallel()
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		defer cancel()
+
+		client, db := coderdtest.NewWithDatabase(t, nil)
+		first := coderdtest.CreateFirstUser(t, client)
+		_ = dbgen.User(t, db, database.User{
+			Email:    "test2@coder.com",
+			Username: "test2",
+		})
+		// nolint:gocritic // Unit test
+		err := db.UpdateUserGithubComUserID(dbauthz.AsSystemRestricted(ctx), database.UpdateUserGithubComUserIDParams{
+			ID: first.UserID,
+			GithubComUserID: sql.NullInt64{
+				Int64: 123,
+				Valid: true,
+			},
+		})
+		require.NoError(t, err)
+		res, err := client.Users(ctx, codersdk.UsersRequest{
+			SearchQuery: "github_com_user_id:123",
+		})
+		require.NoError(t, err)
+		require.Len(t, res.Users, 1)
+		require.Equal(t, res.Users[0].ID, first.UserID)
+	})
 }
 
 func TestGetUsersPagination(t *testing.T) {

diff --git a/docs/reference/cli/users_list.md b/docs/reference/cli/users_list.md