feat(gitea): add Actions API support: list filters, run/job endpoints, dispatch, and richer types

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-03-02 - 1.4.0 - feat(gitea)
+add Actions API support: list filters, run/job endpoints, dispatch, and richer types
+
+- Introduce IActionRunListOptions to allow filtering action runs by status, branch, event, and actor
+- Update getActionRuns to accept filtering options and build URL query parameters
+- Add new client methods: getActionRun, getJobLog, rerunAction, cancelAction, and dispatchWorkflow
+- Expand IGiteaActionRun and IGiteaActionRunJob shapes and add IGiteaActionRunJobStep for more detailed run/job metadata
+- Export new types (IActionRunListOptions, IGiteaActionRunJobStep) from the package index
+
 ## 2026-03-02 - 1.3.0 - feat(gitea)
 add repository branches and tags support: new IGiteaBranch/IGiteaTag interfaces and getRepoBranches/getRepoTags client methods
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@apiclient.xyz/gitea',
-  version: '1.3.0',
+  version: '1.4.0',
   description: 'A TypeScript client for the Gitea API, providing easy access to repositories, organizations, secrets, and action runs.'
 }

ts/gitea.classes.giteaclient.ts

@@ -11,6 +11,7 @@ import type {
   IGiteaActionRunJob,
   ITestConnectionResult,
   IListOptions,
+  IActionRunListOptions,
 } from './gitea.interfaces.js';
 
 export class GiteaClient {
@@ -259,30 +260,77 @@ export class GiteaClient {
   // Action Runs
   // ---------------------------------------------------------------------------
 
-  public async getActionRuns(ownerRepo: string, opts?: IListOptions): Promise<IGiteaActionRun[]> {
+  /**
+   * List action runs for a repository with optional filters.
+   * Supports status, branch, event, actor filtering.
+   */
+  public async getActionRuns(ownerRepo: string, opts?: IActionRunListOptions): Promise<IGiteaActionRun[]> {
     const page = opts?.page || 1;
     const limit = opts?.perPage || 30;
-    const body = await this.request<any>('GET', `/api/v1/repos/${ownerRepo}/actions/runs?page=${page}&limit=${limit}`);
+    let url = `/api/v1/repos/${ownerRepo}/actions/runs?page=${page}&limit=${limit}`;
+    if (opts?.status) url += `&status=${encodeURIComponent(opts.status)}`;
+    if (opts?.branch) url += `&branch=${encodeURIComponent(opts.branch)}`;
+    if (opts?.event) url += `&event=${encodeURIComponent(opts.event)}`;
+    if (opts?.actor) url += `&actor=${encodeURIComponent(opts.actor)}`;
+    const body = await this.request<any>('GET', url);
     return body.workflow_runs || body;
   }
 
+  /**
+   * Get a single action run's full details.
+   */
+  public async getActionRun(ownerRepo: string, runId: number): Promise<IGiteaActionRun> {
+    return this.request<IGiteaActionRun>(
+      'GET',
+      `/api/v1/repos/${ownerRepo}/actions/runs/${runId}`,
+    );
+  }
+
+  /**
+   * List jobs for an action run.
+   */
   public async getActionRunJobs(ownerRepo: string, runId: number): Promise<IGiteaActionRunJob[]> {
     const body = await this.request<any>('GET', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/jobs`);
     return body.jobs || body;
   }
 
+  /**
+   * Get a job's raw log output.
+   */
   public async getJobLog(ownerRepo: string, jobId: number): Promise<string> {
     return this.requestText('GET', `/api/v1/repos/${ownerRepo}/actions/jobs/${jobId}/logs`);
   }
 
+  /**
+   * Re-run an action run.
+   */
   public async rerunAction(ownerRepo: string, runId: number): Promise<void> {
     await this.request('POST', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/rerun`);
   }
 
+  /**
+   * Cancel a running action run.
+   */
   public async cancelAction(ownerRepo: string, runId: number): Promise<void> {
     await this.request('POST', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/cancel`);
   }
 
+  /**
+   * Dispatch a workflow (trigger manually).
+   */
+  public async dispatchWorkflow(
+    ownerRepo: string,
+    workflowId: string,
+    ref: string,
+    inputs?: Record<string, string>,
+  ): Promise<void> {
+    await this.request(
+      'POST',
+      `/api/v1/repos/${ownerRepo}/actions/workflows/${encodeURIComponent(workflowId)}/dispatches`,
+      { ref, inputs: inputs || {} },
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // Repository Deletion
   // ---------------------------------------------------------------------------

ts/gitea.interfaces.ts

@@ -1,3 +1,37 @@
+// ---------------------------------------------------------------------------
+// Common
+// ---------------------------------------------------------------------------
+
+export interface ITestConnectionResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface IListOptions {
+  search?: string;
+  page?: number;
+  perPage?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Action Run list options
+// ---------------------------------------------------------------------------
+
+export interface IActionRunListOptions extends IListOptions {
+  /** Filter by run status (waiting, running, success, failure, cancelled) */
+  status?: string;
+  /** Filter by head branch */
+  branch?: string;
+  /** Filter by trigger event (push, pull_request, schedule, workflow_dispatch, …) */
+  event?: string;
+  /** Filter by the user who triggered the run */
+  actor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Users
+// ---------------------------------------------------------------------------
+
 export interface IGiteaUser {
   id: number;
   login: string;
@@ -6,6 +40,10 @@ export interface IGiteaUser {
   avatar_url: string;
 }
 
+// ---------------------------------------------------------------------------
+// Repositories
+// ---------------------------------------------------------------------------
+
 export interface IGiteaRepository {
   id: number;
   name: string;
@@ -23,6 +61,10 @@ export interface IGiteaRepository {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Organizations
+// ---------------------------------------------------------------------------
+
 export interface IGiteaOrganization {
   id: number;
   name: string;
@@ -32,32 +74,86 @@ export interface IGiteaOrganization {
   repo_count: number;
 }
 
+// ---------------------------------------------------------------------------
+// Secrets
+// ---------------------------------------------------------------------------
+
 export interface IGiteaSecret {
   name: string;
   created_at: string;
 }
 
+// ---------------------------------------------------------------------------
+// Action Runs
+// ---------------------------------------------------------------------------
+
 export interface IGiteaActionRun {
   id: number;
   name: string;
+  workflow_id: string;
   status: string;
   conclusion: string;
   head_branch: string;
   head_sha: string;
   html_url: string;
   event: string;
+  run_number: number;
+  run_attempt: number;
   run_duration: number;
   created_at: string;
+  updated_at: string;
+  started_at: string;
+  actor: IGiteaUser;
+  trigger_actor: IGiteaUser;
+  repository: {
+    id: number;
+    name: string;
+    full_name: string;
+    html_url: string;
+  };
+  head_commit: {
+    id: string;
+    message: string;
+    timestamp: string;
+  };
 }
 
+// ---------------------------------------------------------------------------
+// Action Run Jobs
+// ---------------------------------------------------------------------------
+
 export interface IGiteaActionRunJob {
   id: number;
+  run_id: number;
   name: string;
+  workflow_name: string;
+  head_branch: string;
+  head_sha: string;
   status: string;
   conclusion: string;
+  html_url: string;
   run_duration: number;
+  started_at: string;
+  completed_at: string;
+  steps: IGiteaActionRunJobStep[];
+  labels: string[];
+  runner_id: number;
+  runner_name: string;
 }
 
+export interface IGiteaActionRunJobStep {
+  name: string;
+  number: number;
+  status: string;
+  conclusion: string;
+  started_at: string;
+  completed_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Branches & Tags
+// ---------------------------------------------------------------------------
+
 export interface IGiteaBranch {
   name: string;
   commit: {
@@ -72,14 +168,3 @@ export interface IGiteaTag {
     sha: string;
   };
 }
-
-export interface ITestConnectionResult {
-  ok: boolean;
-  error?: string;
-}
-
-export interface IListOptions {
-  search?: string;
-  page?: number;
-  perPage?: number;
-}

ts/index.ts

@@ -8,7 +8,9 @@ export type {
   IGiteaTag,
   IGiteaActionRun,
   IGiteaActionRunJob,
+  IGiteaActionRunJobStep,
   ITestConnectionResult,
   IListOptions,
+  IActionRunListOptions,
 } from './gitea.interfaces.js';
 export { commitinfo } from './00_commitinfo_data.js';