Add GitHub API compatibility for workflow runs filtering #34894

bdruth · 2025-06-28T21:16:45Z

Summary

Implements additional query parameters for the workflow runs API to match GitHub's REST API specification.

Add exclude_pull_requests query parameter
Add check_suite_id parameter
Add created parameter with date range and comparison support
Add workflow-specific endpoint /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs

Builds on the workflow API foundation from #33964 to provide additional GitHub API compatibility.

Test plan

Unit tests added for new filtering options in FindRunOptions.ToConds()
Unit tests added for API parameter parsing logic
New endpoint follows GitHub API specification exactly

Reference

GitHub API Documentation: https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow
Related PR: Add workflow_run api + webhook #33964

Implements additional query parameters for the workflow runs API to match GitHub's REST API specification. - Add `exclude_pull_requests` query parameter - Add `check_suite_id` parameter - Add `created` parameter with date range and comparison support - Add workflow-specific endpoint `/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs` Builds on the workflow API foundation from go-gitea#33964 to provide additional GitHub API compatibility. Reference: https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow

Add missing query parameters to the Swagger documentation for the workflow runs listing endpoint to match GitHub's API: actor, branch, event, status, created, exclude_pull_requests, check_suite_id, and head_sha.

…efix+TrimPrefix

routers/api/v1/shared/action.go

routers/api/v1/shared/action_list_runs_test.go

bdruth · 2025-06-29T17:33:59Z

✅ Review Comments Addressed

Thanks for the feedback @wxiaoguang! I've addressed all the review comments:

Changes Made:

Use ctx.FormBool - Replaced manual string checking for exclude_pull_requests parameter with the cleaner ctx.FormBool("exclude_pull_requests") approach
Fixed unicode escape - Changed \u002e to simple .. in the date range parsing logic
Enhanced date format support - Added parseISO8601DateRange helper function that properly handles:
- Simple dates: 2023-01-01
- RFC3339 with timezone: 2017-01-01T01:00:00+07:00
- UTC Z-suffix: 2016-03-21T14:11:00Z
- No timezone: 2006-01-02T15:04:05
Simplified test helpers - Updated tests to use contexttest.MockAPIContext(t, "user2/repo1?key=value") instead of manual form value setting, as suggested

Quality Checks:

✅ All tests passing (4/4)
✅ make fmt clean
✅ make lint-backend - 0 issues
✅ Code compiles without errors

The implementation now fully matches GitHub's API date format specification and follows Gitea's code patterns.

lunny · 2025-06-29T18:50:03Z

models/actions/run_list.go

+		cond = cond.And(builder.Neq{"`action_run`.trigger_event": webhook_module.HookEventPullRequest})
+	}
+	if opts.CheckSuiteID > 0 {
+		cond = cond.And(builder.Eq{"`action_run`.check_suite_id": opts.CheckSuiteID})


There is no such column at the moment.

So, take that out, that small part of the GitHub API compatibility won't exist, but it's a pretty minor aspect, I think?

It seem that this PR is written by AI, and the non-existing column is caused by AI hallucination?

We need to make sure every line you proposed to change should be fully understood and has a clear meaning, I think?

To be clear: AI is good, I also use AI. I mean: I think we shouldn't keep the non-existing column in code, we need to leave a clear comment for this case.

Yeah, yeah - for sure. So, remove it and leave a comment somewhere ... noticeable that the API is compatible except for this field. I'll get to work on that.

OK, I think I got a little screwy with the commits, but all the changes seem to be there again. I left the check_suite_id in the swagger with a description that it's not supported - does that seem appropriate?

The CheckSuiteID parameter was referencing a non-existent 'check_suite_id' column in the action_run table. This commit removes the hallucinated database schema reference while maintaining API compatibility. Changes: - Remove CheckSuiteID field from FindRunOptions struct - Remove check_suite_id database query condition - Remove parameter handling logic from shared action handler - Remove related tests for non-functional feature - Update Swagger docs to indicate parameter is not supported in Gitea API - Maintain GitHub API compatibility by keeping parameter documented The check_suite_id parameter is now silently ignored when provided, with clear documentation that it's not supported in Gitea.

ChristopherHX · 2025-06-30T16:06:21Z

routers/api/v1/shared/action_list_runs_test.go

+// TestListRunsWorkflowFiltering tests that ListRuns properly handles
+// the workflow_id path parameter for filtering runs by workflow.
+func TestListRunsWorkflowFiltering(t *testing.T) {
+	unittest.PrepareTestEnv(t)
+
+	ctx, _ := contexttest.MockAPIContext(t, "user2/repo1")
+	contexttest.LoadRepo(t, ctx, 1)
+	contexttest.LoadUser(t, ctx, 2)
+
+	// Test case 1: With workflow_id parameter (simulating /workflows/{workflow_id}/runs endpoint)
+	ctx.SetPathParam("workflow_id", "test-workflow-123")
+
+	// Simulate the FindRunOptions creation that happens in ListRuns
+	opts := actions_model.FindRunOptions{
+		OwnerID:    0,
+		RepoID:     ctx.Repo.Repository.ID,
+		WorkflowID: ctx.PathParam("workflow_id"), // This is the key change being tested
+	}
+
+	// Verify the WorkflowID is correctly extracted from path parameter
+	assert.Equal(t, "test-workflow-123", opts.WorkflowID)
+	assert.Equal(t, ctx.Repo.Repository.ID, opts.RepoID)
+	assert.Equal(t, int64(0), opts.OwnerID)
+
+	// Test case 2: Without workflow_id parameter (general /runs endpoint)
+	ctx2, _ := contexttest.MockAPIContext(t, "user2/repo1")
+	contexttest.LoadRepo(t, ctx2, 1)
+	contexttest.LoadUser(t, ctx2, 2)
+	// No SetPathParam call - simulates general runs endpoint
+
+	opts2 := actions_model.FindRunOptions{
+		RepoID:     ctx2.Repo.Repository.ID,
+		WorkflowID: ctx2.PathParam("workflow_id"),
+	}
+
+	// Verify WorkflowID is empty when path parameter is not set
+	assert.Empty(t, opts2.WorkflowID)
+	assert.Equal(t, ctx2.Repo.Repository.ID, opts2.RepoID)
+}


This test seem to test, SetPathParam and PathParam instead of the code added into ListRuns.

I would expect this test to depend on the logic Gitea would execute, not on a independent copy.

Yes this test tests that a similar logic in ListRuns could work right now, but does not ensure this works in the future. AI tools are pretty good in generating something that looks very good at first glance

Moving assigning the actions_model.FindRunOptions struct into a private function called by ListRuns and this Test, then you would have some coverage.

Good catch @ChristopherHX - I had actually caught a few other instances where the tests were testing something entirely different or incidental versus the important logic, but I missed this one. Is there some sort of coverage report available where I could do a better audit?

I'll get this fixed up.

Addressed in 6b074cb

- Extract FindRunOptions construction logic from ListRuns into buildRunOptions function - Update TestListRunsWorkflowFiltering and related tests to use actual production code - Tests now verify production logic instead of duplicating parameter parsing - Improved error handling by returning errors instead of direct HTTP responses - Ensures future changes to parameter parsing are properly tested This addresses the issue where tests were bypassing production code logic, making them less reliable for catching regressions.

…h/gitea into feature/enhanced-workflow-runs-api * 'feature/enhanced-workflow-runs-api' of github.com:bdruth/gitea: [skip ci] Updated translations via Crowdin Follow file symlinks in the UI to their target (go-gitea#28835) Fix issue filter (go-gitea#34914) Fix: RPM package download routing & missing package version count (go-gitea#34909) Add support for 3D/CAD file formats preview (go-gitea#34794) Add a `login`/`login-name`/`username` disambiguation to affected endpoint parameters and response/request models (go-gitea#34901) Improve tags list page (go-gitea#34898) [skip ci] Updated translations via Crowdin docs: fix typo in pull request merge warning message text (go-gitea#34899) Refactor container package (go-gitea#34877) [skip ci] Updated translations via Crowdin

GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Jun 28, 2025

github-actions bot added modifies/api This PR adds API routes or modifies them modifies/go Pull requests that update Go code labels Jun 28, 2025

Update Swagger documentation for workflow runs API

aeaa2c1

Add missing query parameters to the Swagger documentation for the workflow runs listing endpoint to match GitHub's API: actor, branch, event, status, created, exclude_pull_requests, check_suite_id, and head_sha.

bdruth force-pushed the feature/enhanced-workflow-runs-api branch from 528de08 to aeaa2c1 Compare June 28, 2025 21:36

bdruth added 2 commits June 28, 2025 16:41

run make fmt

722ac05

Apply Go modernization fixes - use strings.CutPrefix instead of HasPr…

695496c

…efix+TrimPrefix

lunny added the topic/api Concerns mainly the API label Jun 28, 2025

lunny added this to the 1.25.0 milestone Jun 28, 2025

wxiaoguang reviewed Jun 29, 2025

View reviewed changes

routers/api/v1/shared/action.go Outdated Show resolved Hide resolved

wxiaoguang reviewed Jun 29, 2025

View reviewed changes

routers/api/v1/shared/action.go Outdated Show resolved Hide resolved

wxiaoguang reviewed Jun 29, 2025

View reviewed changes

routers/api/v1/shared/action.go Outdated Show resolved Hide resolved

wxiaoguang reviewed Jun 29, 2025

View reviewed changes

routers/api/v1/shared/action_list_runs_test.go Outdated Show resolved Hide resolved

lunny reviewed Jun 29, 2025

View reviewed changes

bdruth force-pushed the feature/enhanced-workflow-runs-api branch from 8b7ed3a to 63d924d Compare June 30, 2025 15:42

bdruth force-pushed the feature/enhanced-workflow-runs-api branch from 63d924d to 1b9b410 Compare June 30, 2025 15:45

bdruth added 2 commits June 30, 2025 13:08

Merge branch 'main' into feature/enhanced-workflow-runs-api

0a17b7a

Merge branch 'main' into feature/enhanced-workflow-runs-api

ac87911

ChristopherHX reviewed Jul 1, 2025

View reviewed changes

bdruth added 3 commits July 4, 2025 10:41

Merge branch 'main' into feature/enhanced-workflow-runs-api

aff4e64

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add GitHub API compatibility for workflow runs filtering #34894

Add GitHub API compatibility for workflow runs filtering #34894

bdruth commented Jun 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bdruth commented Jun 29, 2025

Uh oh!

lunny Jun 29, 2025

Uh oh!

bdruth Jun 29, 2025

Uh oh!

wxiaoguang Jun 30, 2025

Uh oh!

wxiaoguang Jun 30, 2025

Uh oh!

bdruth Jun 30, 2025

Uh oh!

bdruth Jun 30, 2025

Uh oh!

ChristopherHX Jun 30, 2025

Uh oh!

bdruth Jul 1, 2025

Uh oh!

bdruth Jul 4, 2025

Uh oh!

Uh oh!

Uh oh!

Add GitHub API compatibility for workflow runs filtering #34894

Are you sure you want to change the base?

Add GitHub API compatibility for workflow runs filtering #34894

Conversation

bdruth commented Jun 28, 2025

Summary

Test plan

Reference

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bdruth commented Jun 29, 2025

✅ Review Comments Addressed

Changes Made:

Quality Checks:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!