Skip to content

feat: Add JSDoc Anotations to Jobs API #3831

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
X-Guardian wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: Add JSDoc Anotations to Jobs API #3831

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4291c55
Add JSDoc to Jobs API
Feb 1, 2026
fd2c22b
Fix formatting
Feb 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/core/src/resources/Gitlab.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,12 @@ export interface Gitlab<C extends boolean = false> extends BaseResource<C> {
IssueStateEvents: IssueStateEvents<C>;
IssueWeightEvents: IssueWeightEvents<C>;
JobArtifacts: JobArtifacts<C>;
/**
* Jobs API resource for managing GitLab CI/CD jobs.
* Provides methods to list, cancel, retry, and manage jobs and their artifacts.
*
* @see {@link https://docs.gitlab.com/api/jobs/}
*/
Jobs: Jobs<C>;
MergeRequestApprovals: MergeRequestApprovals<C>;
MergeRequestAwardEmojis: MergeRequestAwardEmojis<C>;
Expand Down
108 changes: 106 additions & 2 deletions packages/core/src/resources/Jobs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,15 +114,32 @@ export interface JobVariableAttributeOption extends Record<string, unknown> {
value: string;
}

/**
* Jobs API resource for managing GitLab CI/CD jobs.
* Provides methods to list, cancel, retry, and manage jobs and their artifacts.
*
* @see {@link https://docs.gitlab.com/api/jobs/}
*/
export class Jobs<C extends boolean = false> extends BaseResource<C> {
/**
* Get a list of jobs in a project.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param options - Options object for filtering and pagination.
* @returns A promise that resolves to an array of job schemas.
* @see {@link https://docs.gitlab.com/api/jobs/#list-project-jobs}
*/
all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
projectId: string | number,
{
pipelineId,
...options
}: {
/** Filter jobs by pipeline ID. If provided, returns jobs for that specific pipeline. */
pipelineId?: number;
/** Filter jobs by scope(s). Can be a single JobScope or array of JobScope values. */
scope?: JobScope | JobScope[];
/** Whether to include retried jobs in the results. */
includeRetried?: boolean;
} & BaseRequestOptions<E> &
PaginationRequestOptions<P> = {} as any,
Expand All @@ -134,10 +151,23 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
return RequestHelper.get<JobSchema[]>()(this, url, options);
}

/**
* Get a list of trigger jobs for a pipeline.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param pipelineId - The ID of the pipeline.
* @param options - Options object for filtering.
* @returns A promise that resolves to an array of bridge schemas.
* @see {@link https://docs.gitlab.com/api/jobs/#list-pipeline-trigger-jobs}
*/
allPipelineBridges<E extends boolean = false>(
projectId: string | number,
pipelineId: number,
options?: { scope?: JobScope | JobScope[] } & Sudo & ShowExpanded<E>,
options?: {
/** Filter bridges by scope(s). Can be a single JobScope or array of JobScope values. */
scope?: JobScope | JobScope[];
} & Sudo &
ShowExpanded<E>,
): Promise<GitlabAPIResponse<BridgeSchema[], C, E, void>> {
return RequestHelper.get<BridgeSchema[]>()(
this,
Expand All @@ -146,6 +176,15 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* Cancel a single job of a project.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the job to cancel.
* @param options - Additional request options.
* @returns A promise that resolves to the canceled job schema.
* @see {@link https://docs.gitlab.com/api/jobs/#cancel-a-job}
*/
cancel<E extends boolean = false>(
projectId: string | number,
jobId: number,
Expand All @@ -158,6 +197,15 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* Erase a single job of a project (remove job artifacts and a job log).
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the job to erase.
* @param options - Additional request options.
* @returns A promise that resolves to the erased job schema.
* @see {@link https://docs.gitlab.com/api/jobs/#erase-a-job}
*/
erase<E extends boolean = false>(
projectId: string | number,
jobId: number,
Expand All @@ -170,10 +218,23 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* For a job in manual status, trigger an action to start the job.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the manual job to play.
* @param options - Options object for playing the job.
* @returns A promise that resolves to the played job schema.
* @see {@link https://docs.gitlab.com/api/jobs/#run-a-job}
*/
play<E extends boolean = false>(
projectId: string | number,
jobId: number,
options?: { jobVariablesAttributes: JobVariableAttributeOption[] } & Sudo & ShowExpanded<E>,
options?: {
/** Array of job variable attributes to pass when playing the job. */
jobVariablesAttributes?: JobVariableAttributeOption[];
} & Sudo &
ShowExpanded<E>,
): Promise<GitlabAPIResponse<JobSchema, C, E, void>> {
return RequestHelper.post<JobSchema>()(
this,
Expand All @@ -182,6 +243,15 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* Retry a single job of a project.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the job to retry.
* @param options - Additional request options.
* @returns A promise that resolves to the retried job schema.
* @see {@link https://docs.gitlab.com/api/jobs/#retry-a-job}
*/
retry<E extends boolean = false>(
projectId: string | number,
jobId: number,
Expand All @@ -194,6 +264,15 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* Get a single job of a project.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the job.
* @param options - Additional request options.
* @returns A promise that resolves to the job schema.
* @see {@link https://docs.gitlab.com/api/jobs/#get-a-single-job}
*/
show<E extends boolean = false>(
projectId: string | number,
jobId: number,
Expand All @@ -206,6 +285,14 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
);
}

/**
* Retrieve the job that generated a job token.
*
* @param options - Additional request options.
* @returns A promise that resolves to the current job schema.
* @throws Error if `job-token` header is missing.
* @see {@link https://docs.gitlab.com/api/jobs/#get-job-tokens-job}
*/
showConnectedJob<E extends boolean = false>(
options?: Sudo & ShowExpanded<E>,
): Promise<GitlabAPIResponse<JobSchema, C, E, void>> {
Expand All @@ -214,6 +301,14 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
return RequestHelper.get<JobSchema>()(this, 'job', options);
}

/**
* Retrieve the job that generated the CI_JOB_TOKEN, along with a list of allowed agents.
*
* @param options - Additional request options.
* @returns A promise that resolves to the Kubernetes agents schema.
* @throws Error if `job-token` header is missing.
* @see {@link https://docs.gitlab.com/api/jobs/#get-gitlab-agent-for-kubernetes-by-ci_job_token}
*/
showConnectedJobK8Agents<E extends boolean = false>(
options?: Sudo & ShowExpanded<E>,
): Promise<GitlabAPIResponse<JobKubernetesAgentsSchema, C, E, void>> {
Expand All @@ -222,6 +317,15 @@ export class Jobs<C extends boolean = false> extends BaseResource<C> {
return RequestHelper.get<JobKubernetesAgentsSchema>()(this, 'job/allowed_agents', options);
}

/**
* Get a log (trace) of a specific job of a project.
*
* @param projectId - The ID or URL-encoded path of the project.
* @param jobId - The ID of the job.
* @param options - Additional request options.
* @returns A promise that resolves to the job trace/log as a string.
* @see {@link https://docs.gitlab.com/api/jobs/#get-a-log-file}
*/
showLog<E extends boolean = false>(
projectId: string | number,
jobId: number,
Expand Down
Loading