feat(api): add REST API for repository project boards

Cherry-pick of upstream PR go-gitea/gitea#37518 onto feat/projects-api. The PR is itself a rebase of #36831 onto main, adapted for the multi-projects-per-issue model added in #36784. Endpoints (all under /repos/{owner}/{repo}/projects...): GET . list projects POST . create project GET /{id} get project PATCH /{id} update project DELETE /{id} delete project GET /{id}/columns list columns POST /{id}/columns create column PATCH /columns/{id} update column DELETE /columns/{id} delete column GET /columns/{id}/issues list issues in column POST /columns/{id}/issues/{issue_id} add/move issue to column DELETE /columns/{id}/issues/{issue_id} remove issue from column POST /columns/{id}/issues/{issue_id}/move move between columns Source: https://github.com/go-gitea/gitea/pull/37518
2026-05-11 15:41:15 +03:00
parent 187daac598
commit 1011241a67
22 changed files with 4306 additions and 139 deletions
@@ -99,7 +99,7 @@ func toIssue(ctx context.Context, doer *user_model.User, issue *issues_model.Iss
 		return &api.Issue{}
 	}
 	if len(issue.Projects) > 0 {
-		apiIssue.Projects = ToAPIProjectList(issue.Projects)
+		apiIssue.Projects = ToProjectList(ctx, issue.Projects, doer)
 	}

 	if err := issue.LoadAssignees(ctx); err != nil {
@@ -4,34 +4,179 @@
 package convert

 import (
+	"context"
+	"fmt"
+
 	project_model "code.gitea.io/gitea/models/project"
+	user_model "code.gitea.io/gitea/models/user"
+	"code.gitea.io/gitea/modules/container"
 	api "code.gitea.io/gitea/modules/structs"
 )

-// ToAPIProject converts a Project to API format
-func ToAPIProject(p *project_model.Project) *api.Project {
-	apiProject := &api.Project{
-		ID:          p.ID,
-		Title:       p.Title,
-		Description: p.Description,
-		OwnerID:     p.OwnerID,
-		RepoID:      p.RepoID,
-		CreatorID:   p.CreatorID,
-		IsClosed:    p.IsClosed,
-		Created:     p.CreatedUnix.AsTime(),
-		Updated:     p.UpdatedUnix.AsTime(),
+func ProjectTemplateTypeToString(t project_model.TemplateType) string {
+	switch t {
+	case project_model.TemplateTypeBasicKanban:
+		return "basic_kanban"
+	case project_model.TemplateTypeBugTriage:
+		return "bug_triage"
+	default:
+		return "none"
 	}
-	if p.IsClosed && p.ClosedDateUnix > 0 {
-		apiProject.Closed = p.ClosedDateUnix.AsTimePtr()
-	}
-	return apiProject
 }

-// ToAPIProjectList converts a list of Projects to API format
-func ToAPIProjectList(projects []*project_model.Project) []*api.Project {
+func ProjectTemplateTypeFromString(s string) (project_model.TemplateType, error) {
+	switch s {
+	case "", "none":
+		return project_model.TemplateTypeNone, nil
+	case "basic_kanban":
+		return project_model.TemplateTypeBasicKanban, nil
+	case "bug_triage":
+		return project_model.TemplateTypeBugTriage, nil
+	default:
+		return 0, fmt.Errorf("invalid template_type %q (expected none, basic_kanban, bug_triage)", s)
+	}
+}
+
+func ProjectCardTypeToString(t project_model.CardType) string {
+	switch t {
+	case project_model.CardTypeImagesAndText:
+		return "images_and_text"
+	default:
+		return "text_only"
+	}
+}
+
+func ProjectCardTypeFromString(s string) (project_model.CardType, error) {
+	switch s {
+	case "", "text_only":
+		return project_model.CardTypeTextOnly, nil
+	case "images_and_text":
+		return project_model.CardTypeImagesAndText, nil
+	default:
+		return 0, fmt.Errorf("invalid card_type %q (expected text_only, images_and_text)", s)
+	}
+}
+
+func ProjectTypeToString(t project_model.Type) string {
+	switch t {
+	case project_model.TypeIndividual:
+		return "individual"
+	case project_model.TypeRepository:
+		return "repository"
+	case project_model.TypeOrganization:
+		return "organization"
+	default:
+		return ""
+	}
+}
+
+// loadProjectCreators batch-fetches creators for the given projects + columns and
+// returns a map keyed by user ID. Errors are surfaced; missing users are silently
+// skipped (their creator field stays nil), matching the convention of other list
+// converters that tolerate deleted users.
+func loadProjectCreators(ctx context.Context, projects []*project_model.Project, columns []*project_model.Column) (map[int64]*user_model.User, error) {
+	idSet := container.Set[int64]{}
+	for _, p := range projects {
+		if p.CreatorID > 0 {
+			idSet.Add(p.CreatorID)
+		}
+	}
+	for _, c := range columns {
+		if c.CreatorID > 0 {
+			idSet.Add(c.CreatorID)
+		}
+	}
+	if len(idSet) == 0 {
+		return map[int64]*user_model.User{}, nil
+	}
+	return user_model.GetUsersMapByIDs(ctx, idSet.Values())
+}
+
+// ToProject converts a project_model.Project to api.Project.
+// Caller is expected to preload p.Repo / p.Owner to avoid N+1 lookups.
+func ToProject(ctx context.Context, p *project_model.Project, doer *user_model.User) *api.Project {
+	creators, _ := loadProjectCreators(ctx, []*project_model.Project{p}, nil)
+	return toProject(ctx, p, doer, creators)
+}
+
+func toProject(ctx context.Context, p *project_model.Project, doer *user_model.User, creators map[int64]*user_model.User) *api.Project {
+	state := api.StateOpen
+	if p.IsClosed {
+		state = api.StateClosed
+	}
+
+	project := &api.Project{
+		ID:              p.ID,
+		Title:           p.Title,
+		Description:     p.Description,
+		OwnerID:         p.OwnerID,
+		RepoID:          p.RepoID,
+		State:           state,
+		TemplateType:    ProjectTemplateTypeToString(p.TemplateType),
+		CardType:        ProjectCardTypeToString(p.CardType),
+		Type:            ProjectTypeToString(p.Type),
+		NumOpenIssues:   p.NumOpenIssues,
+		NumClosedIssues: p.NumClosedIssues,
+		NumIssues:       p.NumIssues,
+		CreatedAt:       p.CreatedUnix.AsTime(),
+		UpdatedAt:       p.UpdatedUnix.AsTime(),
+	}
+
+	if p.ClosedDateUnix > 0 {
+		t := p.ClosedDateUnix.AsTime()
+		project.ClosedAt = &t
+	}
+
+	if creator, ok := creators[p.CreatorID]; ok {
+		project.Creator = ToUser(ctx, creator, doer)
+	}
+
+	if p.Type == project_model.TypeRepository && p.Repo != nil {
+		project.HTMLURL = p.Repo.HTMLURL() + fmt.Sprintf("/projects/%d", p.ID)
+	} else if p.Owner != nil {
+		project.HTMLURL = p.Owner.HTMLURL(ctx) + fmt.Sprintf("/-/projects/%d", p.ID)
+	}
+
+	return project
+}
+
+func ToProjectColumn(ctx context.Context, column *project_model.Column, doer *user_model.User) *api.ProjectColumn {
+	creators, _ := loadProjectCreators(ctx, nil, []*project_model.Column{column})
+	return toProjectColumn(ctx, column, doer, creators)
+}
+
+func toProjectColumn(ctx context.Context, column *project_model.Column, doer *user_model.User, creators map[int64]*user_model.User) *api.ProjectColumn {
+	apiColumn := &api.ProjectColumn{
+		ID:        column.ID,
+		Title:     column.Title,
+		Default:   column.Default,
+		Sorting:   int(column.Sorting),
+		Color:     column.Color,
+		ProjectID: column.ProjectID,
+		NumIssues: column.NumIssues,
+		CreatedAt: column.CreatedUnix.AsTime(),
+		UpdatedAt: column.UpdatedUnix.AsTime(),
+	}
+	if creator, ok := creators[column.CreatorID]; ok {
+		apiColumn.Creator = ToUser(ctx, creator, doer)
+	}
+	return apiColumn
+}
+
+func ToProjectList(ctx context.Context, projects []*project_model.Project, doer *user_model.User) []*api.Project {
+	creators, _ := loadProjectCreators(ctx, projects, nil)
 	result := make([]*api.Project, len(projects))
-	for i := range projects {
-		result[i] = ToAPIProject(projects[i])
+	for i, p := range projects {
+		result[i] = toProject(ctx, p, doer, creators)
+	}
+	return result
+}
+
+func ToProjectColumnList(ctx context.Context, columns []*project_model.Column, doer *user_model.User) []*api.ProjectColumn {
+	creators, _ := loadProjectCreators(ctx, nil, columns)
+	result := make([]*api.ProjectColumn, len(columns))
+	for i, column := range columns {
+		result[i] = toProjectColumn(ctx, column, doer, creators)
 	}
 	return result
 }
@@ -17,6 +17,10 @@ import (
 	"code.gitea.io/gitea/modules/optional"
 )

+// ErrIssueNotInProject is returned when MoveIssuesOnProjectColumn is asked to move
+// issues that aren't yet attached to the column's project.
+var ErrIssueNotInProject = errors.New("all issues have to be added to a project first")
+
 // MoveIssuesOnProjectColumn moves or keeps issues in a column and sorts them inside that column
 func MoveIssuesOnProjectColumn(ctx context.Context, doer *user_model.User, column *project_model.Column, sortedIssueIDs map[int64]int64) error {
 	return db.WithTx(ctx, func(ctx context.Context) error {
@@ -32,7 +36,7 @@ func MoveIssuesOnProjectColumn(ctx context.Context, doer *user_model.User, colum
 			return err
 		}
 		if int(count) != len(sortedIssueIDs) {
-			return errors.New("all issues have to be added to a project first")
+			return ErrIssueNotInProject
 		}

 		issues, err := issues_model.GetIssuesByIDs(ctx, issueIDs)
@@ -63,7 +67,6 @@ func MoveIssuesOnProjectColumn(ctx context.Context, doer *user_model.User, colum
 			if err != nil {
 				return err
 			}
-
 			projectColumnID := projectColumnMap[column.ProjectID]

 			if projectColumnID != column.ID {
@@ -82,16 +85,7 @@ func MoveIssuesOnProjectColumn(ctx context.Context, doer *user_model.User, colum
 				}
 			}

-			// Update the column and sorting for this specific issue in this specific project.
-			// IMPORTANT: The WHERE clause must include both issue_id AND project_id to ensure
-			// that moving an issue's column in one project doesn't affect its column in other
-			// projects when the issue is assigned to multiple projects.
-			_, err = db.GetEngine(ctx).Table("project_issue").
-				Where("issue_id = ? AND project_id = ?", issueID, column.ProjectID).
-				Update(map[string]any{
-					"project_board_id": column.ID,
-					"sorting":          sorting,
-				})
+			_, err = db.Exec(ctx, "UPDATE `project_issue` SET project_board_id=?, sorting=? WHERE issue_id=?", column.ID, sorting, issueID)
 			if err != nil {
 				return err
 			}
@@ -129,7 +123,7 @@ func LoadIssuesAssigneesForProject(ctx context.Context, issuesMap map[int64]issu
 func LoadIssuesFromProject(ctx context.Context, project *project_model.Project, opts *issues_model.IssuesOptions) (results map[int64]issues_model.IssueList, _ error) {
 	issueList, err := issues_model.Issues(ctx, opts.Copy(func(o *issues_model.IssuesOptions) {
 		o.ProjectIDs = []int64{project.ID}
-		o.SortType = "project-column-sorting"
+		o.SortType = issues_model.SortTypeProjectColumnSorting
 	}))
 	if err != nil {
 		return nil, err
@@ -0,0 +1,44 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package project
+
+import (
+	"context"
+
+	"code.gitea.io/gitea/models/db"
+	project_model "code.gitea.io/gitea/models/project"
+	"code.gitea.io/gitea/modules/optional"
+)
+
+// UpdateProjectOptions represents updatable project fields. Fields with no value are left unchanged.
+type UpdateProjectOptions struct {
+	Title       optional.Option[string]
+	Description optional.Option[string]
+	CardType    optional.Option[project_model.CardType]
+	IsClosed    optional.Option[bool]
+}
+
+// UpdateProject applies the provided options to the project atomically.
+func UpdateProject(ctx context.Context, project *project_model.Project, opts UpdateProjectOptions) error {
+	return db.WithTx(ctx, func(ctx context.Context) error {
+		if opts.Title.Has() {
+			project.Title = opts.Title.Value()
+		}
+		if opts.Description.Has() {
+			project.Description = opts.Description.Value()
+		}
+		if opts.CardType.Has() {
+			project.CardType = opts.CardType.Value()
+		}
+		if err := project_model.UpdateProject(ctx, project); err != nil {
+			return err
+		}
+		if opts.IsClosed.Has() && opts.IsClosed.Value() != project.IsClosed {
+			if err := project_model.ChangeProjectStatus(ctx, project, opts.IsClosed.Value()); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}