enhance(api): add GitHub-compatible /repos/{owner}/{repo}/commits/{ref} endpoint (#38770)

Gitea currently exposes the endpoint:
 
`GET /repos/{owner}/{repo}/git/commits/{sha}`
 
to retrieve a single commit. However, GitHub provides the equivalent
endpoint as:
 
`GET /repos/{owner}/{repo}/commits/{ref}`
 
Applications integrating with both GitHub and Gitea must implement
platform-specific logic to use different endpoints, reducing API
compatibility.
 
Fixes #38225

---------

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Giteabot <teabot@gitea.io>

README.md

@@ -68,7 +68,7 @@ Get more information from [documentation](https://docs.gitea.com/contributing/lo
 
 ## Official and Third-Party Projects
 
-We provide an official [go-sdk](https://gitea.com/gitea/go-sdk), a CLI tool called [tea](https://gitea.com/gitea/tea) and an [action runner](https://gitea.com/gitea/act_runner) for Gitea Action.
+We provide an official [go-sdk](https://gitea.com/gitea/go-sdk), a CLI tool called [tea](https://gitea.com/gitea/tea) and an [action runner](https://gitea.com/gitea/runner) for Gitea Action.
 
 We maintain a list of Gitea-related projects at [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea), where you can discover more third-party projects, including SDKs, plugins, themes, and more.
 

README.zh-cn.md

@@ -76,7 +76,7 @@
 
 ## 官方和第三方项目
 
-我们提供了一个官方的 [go-sdk](https://gitea.com/gitea/go-sdk)，一个名为 [tea](https://gitea.com/gitea/tea) 的 CLI 工具和一个 Gitea Action 的 [action runner](https://gitea.com/gitea/act_runner)。
+我们提供了一个官方的 [go-sdk](https://gitea.com/gitea/go-sdk)，一个名为 [tea](https://gitea.com/gitea/tea) 的 CLI 工具和一个 Gitea Action 的 [action runner](https://gitea.com/gitea/runner)。
 
 我们在 [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea) 维护了一个 Gitea 相关项目的列表，您可以在那里发现更多的第三方项目，包括 SDK、插件、主题等。
 

README.zh-tw.md

@@ -76,7 +76,7 @@
 
 ## 官方和第三方項目
 
-我們提供了一個官方的 [go-sdk](https://gitea.com/gitea/go-sdk)，一個名為 [tea](https://gitea.com/gitea/tea) 的 CLI 工具和一個 Gitea Action 的 [action runner](https://gitea.com/gitea/act_runner)。
+我們提供了一個官方的 [go-sdk](https://gitea.com/gitea/go-sdk)，一個名為 [tea](https://gitea.com/gitea/tea) 的 CLI 工具和一個 Gitea Action 的 [action runner](https://gitea.com/gitea/runner)。
 
 我們在 [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea) 維護了一個 Gitea 相關項目的列表，您可以在那裡發現更多的第三方項目，包括 SDK、插件、主題等。
 

modelmigration/v1_20/v248.go

@@ -11,7 +11,7 @@ import (
 
 func AddVersionToActionRunner(_ context.Context, x base.EngineMigration) error {
 	type ActionRunner struct {
-		Version string `xorm:"VARCHAR(64)"` // the version of act_runner
+		Version string `xorm:"VARCHAR(64)"` // the version of the runner
 	}
 
 	return x.Sync(new(ActionRunner))

models/actions/runner.go

@@ -58,7 +58,7 @@ type ActionRunner struct {
 	LastOnline timeutil.TimeStamp `xorm:"index"`
 	LastActive timeutil.TimeStamp `xorm:"index"`
 
-	// Store labels defined in state file (default: .runner file) of `act_runner`
+	// Store labels defined in state file (default: .runner file) of the `runner`
 	AgentLabels []string `xorm:"TEXT"`
 	// Store if this is a runner that only ever get one single job assigned
 	Ephemeral bool `xorm:"ephemeral NOT NULL DEFAULT false"`

routers/api/actions/artifacts.go

@@ -143,7 +143,7 @@ func ArtifactContexter() func(next http.Handler) http.Handler {
 				return
 			}
 
-			// New act_runner uses jwt to authenticate
+			// New runner uses jwt to authenticate
 			tID, err := actions_service.ParseAuthorizationToken(req)
 
 			var task *actions.ActionTask
@@ -160,7 +160,7 @@ func ArtifactContexter() func(next http.Handler) http.Handler {
 					return
 				}
 			} else {
-				// Old act_runner uses GITEA_TOKEN to authenticate
+				// Old runner uses GITEA_TOKEN to authenticate
 				authToken := strings.TrimPrefix(authHeader, "Bearer ")
 
 				task, err = actions.GetRunningTaskByToken(req.Context(), authToken)

routers/api/actions/artifacts_utils.go

@@ -69,7 +69,7 @@ func validateArtifactHash(ctx *ArtifactContext, artifactName string) bool {
 func parseArtifactItemPath(ctx *ArtifactContext) (string, string, bool) {
 	// itemPath is generated from upload-artifact action
 	// it's formatted as {artifact_name}/{artfict_path_in_runner}
-	// act_runner in host mode on Windows, itemPath is joined by Windows slash '\'
+	// runner in host mode on Windows, itemPath is joined by Windows slash '\'
 	itemPath := util.PathJoinRelX(ctx.Req.URL.Query().Get("itemPath"))
 	artifactName := strings.Split(itemPath, "/")[0]
 	artifactPath := strings.TrimPrefix(itemPath, artifactName+"/")

routers/api/v1/api.go

@@ -1484,7 +1484,11 @@ func Routes() *web.Router {
 						Post(reqToken(), reqRepoWriter(unit.TypeCode), bind(api.CreateStatusOption{}), repo.NewCommitStatus)
 				}, reqRepoReader(unit.TypeCode))
 				m.Group("/commits", func() {
-					m.Get("", context.ReferencesGitRepo(), repo.GetAllCommits)
+					m.Group("", func() {
+						m.Get("", repo.GetAllCommits)
+						m.Get("/{sha}", repo.GetSingleCommit) // GitHub-compatible endpoint
+						m.Get("/{sha}.{diffType:diff|patch}", repo.DownloadCommitDiffOrPatch)
+					}, context.ReferencesGitRepo(true))
 					m.PathGroup("/*", func(g *web.RouterPathGroup) {
 						// Mis-configured reverse proxy might decode the `%2F` to slash ahead, so we need to support both formats (escaped, unescaped) here.
 						// It also matches GitHub's behavior

routers/api/v1/repo/commits.go

@@ -24,7 +24,7 @@ import (
 func GetSingleCommit(ctx *context.APIContext) {
 	// swagger:operation GET /repos/{owner}/{repo}/git/commits/{sha} repository repoGetSingleCommit
 	// ---
-	// summary: Get a single commit from a repository
+	// summary: Get a single commit from a repository, it has a GitHub-compatible alias "/repos/{owner}/{repo}/commits/{ref}"
 	// produces:
 	// - application/json
 	// parameters:

services/actions/cleanup.go

@@ -239,10 +239,10 @@ func DeleteRun(ctx context.Context, run *actions_model.ActionRun) error {
 
 	if err := db.WithTx(ctx, func(ctx context.Context) error {
 		// TODO: Deleting task records could break current ephemeral runner implementation. This is a temporary workaround suggested by ChristopherHX.
-		// Since you delete potentially the only task an ephemeral act_runner has ever run, please delete the affected runners first.
+		// Since you delete potentially the only task an ephemeral runner has ever run, please delete the affected runners first.
 		// one of
 		//    call cleanup ephemeral runners first
-		//    delete affected ephemeral act_runners
+		//    delete affected ephemeral runners
 		//    I would make ephemeral runners fully delete directly before formally finishing the task
 		//
 		// See also: https://github.com/go-gitea/gitea/pull/34337#issuecomment-2862222788

services/actions/job_emitter_test.go

@@ -101,7 +101,7 @@ jobs:
     needs: job1
     if: ${{ always() && needs.job1.result == 'success' }}
     steps:
-      - run: echo "will be checked by act_runner"
+      - run: echo "will be checked by runner"
 `)},
 			},
 			want: map[int64]actions_model.Status{2: actions_model.StatusWaiting},
@@ -120,7 +120,7 @@ jobs:
     needs: job1
     if: ${{ always() && needs.job1.result == 'failure' }}
     steps:
-      - run: echo "will be checked by act_runner"
+      - run: echo "will be checked by runner"
 `)},
 			},
 			want: map[int64]actions_model.Status{2: actions_model.StatusWaiting},

templates/swagger/v1-openapi3.generated.json

@@ -20470,7 +20470,7 @@
             "$ref": "#/components/responses/validationError"
           }
         },
-        "summary": "Get a single commit from a repository",
+        "summary": "Get a single commit from a repository, it has a GitHub-compatible alias \"/repos/{owner}/{repo}/commits/{ref}\"",
         "tags": [
           "repository"
         ]

templates/swagger/v1-swagger.generated.json

@@ -9067,7 +9067,7 @@
         "tags": [
           "repository"
         ],
-        "summary": "Get a single commit from a repository",
+        "summary": "Get a single commit from a repository, it has a GitHub-compatible alias \"/repos/{owner}/{repo}/commits/{ref}\"",
         "operationId": "repoGetSingleCommit",
         "parameters": [
           {

tests/integration/api_repo_git_commits_test.go

@@ -26,22 +26,15 @@ func compareCommitFiles(t *testing.T, expect []string, files []*api.CommitAffect
 
 func TestAPIReposGitCommits(t *testing.T) {
 	defer tests.PrepareTestEnv(t)()
-	user := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
-	// Login as User2.
-	session := loginUser(t, user.Name)
+	user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+	session := loginUser(t, user2.Name)
 	token := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeReadRepository)
 
 	// check invalid requests
-	req := NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/12345", user.Name).
-		AddTokenAuth(token)
-	MakeRequest(t, req, http.StatusNotFound)
-
-	req = NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/..", user.Name).
-		AddTokenAuth(token)
+	req := NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/..", user2.Name).AddTokenAuth(token)
 	MakeRequest(t, req, http.StatusUnprocessableEntity)
 
-	req = NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/branch-not-exist", user.Name).
-		AddTokenAuth(token)
+	req = NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/ref-not-exist", user2.Name).AddTokenAuth(token)
 	MakeRequest(t, req, http.StatusNotFound)
 
 	for _, ref := range [...]string{
@@ -50,8 +43,10 @@ func TestAPIReposGitCommits(t *testing.T) {
 		"65f1",   // short sha
 		"65f1bf27bc3bf70f64657658635e66094edbcb4d", // full sha
 	} {
-		req := NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/%s", user.Name, ref).
-			AddTokenAuth(token)
+		req = NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/git/commits/%s", user2.Name, ref).AddTokenAuth(token)
+		MakeRequest(t, req, http.StatusOK)
+		// GitHub-compatible
+		req = NewRequestf(t, "GET", "/api/v1/repos/%s/repo1/commits/%s", user2.Name, ref).AddTokenAuth(token)
 		MakeRequest(t, req, http.StatusOK)
 	}
 }