feat: add deploy tokens (#37306)

Deploy keys only work over SSH. A deploy token is their counterpart for HTTPS: a repository scoped credential, used as the password of a Git request, with read or read and write access. It covers Git operations and LFS, and can be regenerated in place.

Signed-off-by: silverwind <me@silverwind.io>
Co-authored-by: Claude Mythos <noreply@anthropic.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: bircni <bircni@icloud.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

services/auth/basic.go

@@ -29,6 +29,7 @@ const (
 	AccessTokenMethodName = "access_token"
 	OAuth2TokenMethodName = "oauth2_token"
 	ActionTokenMethodName = "action_token"
+	DeployTokenMethodName = "deploy_token"
 )
 
 // Basic implements the Auth interface and authenticates requests (API requests
@@ -41,7 +42,7 @@ func (b *Basic) Name() string {
 	return BasicMethodName
 }
 
-func (b *Basic) parseAuthBasic(req *http.Request) (ret struct{ authToken, uname, passwd string }) {
+func parseAuthBasic(req *http.Request) (ret struct{ authToken, uname, passwd string }) {
 	authHeader := req.Header.Get("Authorization")
 	if authHeader == "" {
 		return ret
@@ -53,7 +54,7 @@ func (b *Basic) parseAuthBasic(req *http.Request) (ret struct{ authToken, uname,
 	uname, passwd := parsed.BasicAuth.Username, parsed.BasicAuth.Password
 
 	// Check if username or password is a token
-	isUsernameToken := len(passwd) == 0 || passwd == "x-oauth-basic"
+	isUsernameToken := passwd == "" || passwd == "x-oauth-basic"
 	// Assume username is token
 	authToken := uname
 	if !isUsernameToken {
@@ -122,7 +123,7 @@ func (b *Basic) VerifyAuthToken(req *http.Request, w http.ResponseWriter, store
 // name/token on successful validation.
 // Returns nil if header is empty or validation fails.
 func (b *Basic) Verify(req *http.Request, w http.ResponseWriter, store DataStore, sess SessionStore) (*user_model.User, error) {
-	parseBasicRet := b.parseAuthBasic(req)
+	parseBasicRet := parseAuthBasic(req)
 	authToken, uname, passwd := parseBasicRet.authToken, parseBasicRet.uname, parseBasicRet.passwd
 	if authToken == "" && uname == "" {
 		return nil, nil //nolint:nilnil // the auth method is not applicable

services/auth/deploy_token.go

@@ -0,0 +1,47 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"net/http"
+
+	deploykey_model "gitea.dev/models/deploykey"
+	user_model "gitea.dev/models/user"
+	"gitea.dev/modules/log"
+)
+
+var _ Method = &DeployToken{}
+
+// DeployToken authenticates a deploy key token given as HTTP basic auth credential.
+// Only add it to an auth group where a repo scoped credential makes sense.
+type DeployToken struct{}
+
+func (d *DeployToken) Name() string {
+	return DeployTokenMethodName
+}
+
+// Verify returns a user that stands for the deploy key alone. Its permissions come from the key,
+// see access_model.getDeployKeyRepoPermission, so the request can never reach another repository
+// or exceed the access mode of the key.
+func (d *DeployToken) Verify(req *http.Request, _ http.ResponseWriter, store DataStore, _ SessionStore) (*user_model.User, error) {
+	authToken := parseAuthBasic(req).authToken
+	if authToken == "" {
+		return nil, nil //nolint:nilnil // the auth method is not applicable
+	}
+
+	key, err := deploykey_model.VerifyDeployKeyToken(req.Context(), authToken)
+	if err != nil {
+		if deploykey_model.IsErrDeployKeyNotExist(err) {
+			return nil, nil //nolint:nilnil // not a deploy token, let the other methods try
+		}
+		return nil, err
+	}
+
+	if err := deploykey_model.UpdateDeployKeyLastUsed(req.Context(), key.ID); err != nil {
+		log.Error("UpdateDeployKeyUpdated: %v", err)
+	}
+
+	store.GetData()["LoginMethod"] = DeployTokenMethodName
+	return user_model.NewDeployKeyUserWithKeyID(key.ID), nil
+}