Working with CI/CD API and Automation

1. Using CI/CD Pipeline API

Endpoint	Method	Description	Notes
/projects/:id/pipelines	GET	Get list of pipelines for a project	Supports filtering by status, ref, and created_after
/projects/:id/pipelines/:pipeline_id	GET	Get a specific pipeline	Returns detailed pipeline information including jobs and stages
/projects/:id/pipelines	POST	Create a new pipeline	Triggers a new pipeline with optional parameters like ref and variables
/projects/:id/pipelines/:pipeline_id/cancel	POST	Cancel a running pipeline	Only available for pipelines in 'running' or 'pending' status
/projects/:id/pipelines/:pipeline_id/bridge	POST	Bridge a pipeline to another project	Allows cross-project pipeline triggering

Example: Fetching Pipeline Details

curl --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines/456"

Example: Triggering a New Pipeline

curl --request POST \
  --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxxxx" \
  --form "ref=main" \
  --form "variables[key1]=value1" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines"

Note: The GitLab CI/CD API requires a valid PRIVATE-TOKEN for authentication. Ensure that the token has sufficient permissions to access and trigger pipelines in the target project.

2. Triggering Pipelines via API

GitLab CI/CD allows triggering pipelines programmatically using the GitLab API. This is useful for automating pipeline execution based on external events or integrations.

Endpoint	Method	Description
/projects/:id/trigger/pipeline	POST	Triggers a pipeline for a specific project using a trigger token.

Example: Triggering a Pipeline

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"token": "trigger_token", "ref": "main", "variables": {"VAR1": "value1"}}'

Note: The ref parameter specifies the branch or tag to run the pipeline on. Variables can be passed as key-value pairs in the variables object.

Warning: Ensure that the trigger token is kept secure and not exposed in logs or client-side code.

3. Managing Jobs via API

Property	Description	Values
job_id	Unique identifier for the job	`integer`
status	Current status of the job	`created`, `running`, `success`, `failed`, `canceled`
name	Name of the job	`string`
pipeline_id	ID of the pipeline this job belongs to	`integer`

Example: Get job details

curl --header "PRIVATE-TOKEN: glpat-xxxxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/1/jobs/123"

Example: Cancel a job

curl --request PUT \
  --header "PRIVATE-TOKEN: glpat-xxxxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/1/jobs/123/cancel"

Example: Retry a failed job

curl --request POST \
  --header "PRIVATE-TOKEN: glpat-xxxxxxxxxx" \
  "https://gitlab.example.com/api/v4/projects/1/jobs/123/retry"

4. Using Job Tokens (CI_JOB_TOKEN)

The CI_JOB_TOKEN is an automatically generated token available in GitLab CI/CD jobs that allows access to the GitLab API with specific permissions tied to the job's context.

Property	Value	Description
CI_JOB_TOKEN	`***`	Token for API access within the job context

Example: Using CI_JOB_TOKEN to access GitLab API

curl --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" \
  "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID"

Note: The CI_JOB_TOKEN is valid only within the job's runtime and has limited scope based on the project and job permissions.

Warning: Do not expose CI_JOB_TOKEN in job logs or outputs. It should be used securely and never committed to version control.

5. Accessing GitLab API in Jobs

Example: Using GitLab API Token in CI Job

job_name:
  script:
    - "curl --header 'PRIVATE-TOKEN: $GITLAB_API_TOKEN' \"
    - "https://gitlab.example.com/api/v4/projects/123/issues"

Variable	Description	Usage
GITLAB_API_TOKEN	Personal access token with API scope	Used in `curl` or `gitlab-cli` commands
CI_API_V4_URL	Base URL for GitLab API v4	Used to construct API endpoints

Note: The GITLAB_API_TOKEN is automatically provided in CI jobs if the project has a personal access token configured.

Warning: Never expose API tokens in logs or console output. Use masked variables in GitLab CI settings.

6. Configuring Pipeline Webhooks

Property	Description	Default	Notes
webhook_url	URL to send webhook payload	None	Required for enabling webhooks
pipeline_events	Events that trigger webhook	`["push", "merge_request"]`	Supports multiple event types
secret_token	Token to authenticate webhook	None	Optional but recommended for security

Example: Setting up a Webhook

webhook:
  url: https://example.com/webhook
  events:
    - push
    - merge_request
  secret_token: "my-secret"

Note: Webhooks are sent asynchronously and may not be delivered immediately.

Warning: Ensure the webhook endpoint is secure and can handle incoming payloads.

Webhook Event Types

push - Triggered on code push to a branch
merge_request - Triggered on merge request creation or update
pipeline - Triggered when a pipeline completes or fails
job - Triggered on job completion or failure

7. Creating Pipeline Badges

Pipeline badges provide a visual indicator of your CI/CD pipeline's status directly in your project's README or documentation. They can be used to show the current build status, coverage, or other metrics.

Badge Type	URL Format	Description
Build Status	`https://gitlab.example.com/namespace/project/badges/master/build.svg`	Shows the current build status (success, failed, running)
Coverage	`https://gitlab.example.com/namespace/project/badges/master/coverage.svg`	Displays code coverage percentage
License	`https://gitlab.example.com/namespace/project/badges/master/license.svg`	Shows project license information

Example: Adding a Build Status Badge to README.md

<img src="https://gitlab.example.com/namespace/project/badges/master/build.svg" alt="Build Status">

Note: The badge URL requires the project to be public or accessible with appropriate permissions. For private projects, you may need to configure access tokens or use the project's CI_JOB_TOKEN.

Badge Configuration Options

Branch: Specify the branch to get the badge for (e.g., main, develop)
Format: Supported formats are .svg, .png, and .json
Metrics: Available metrics include build status, coverage, and custom metrics

8. Using Coverage Badges

Coverage Badge Type	Endpoint	Description	Notes
Project Coverage Badge	`/projects/:id/coverage_badge.svg`	Displays test coverage percentage for a project	Requires project access and coverage data
Group Coverage Badge	`/groups/:id/coverage_badge.svg`	Shows aggregated coverage for a group of projects	Aggregates coverage from all projects in the group

Example: Adding Coverage Badge to README

<img src="https://gitlab.example.com/my-group/my-project/coverage_badge.svg" alt="Coverage Status">

Note: Coverage badges require that the project has a valid coverage report configured in the CI pipeline.

Warning: The badge will show unknown if no coverage data is found or the project has no CI jobs configured.

9. Implementing Custom Integrations

Example: Triggering a Pipeline via API

curl --request POST \
  --url <span class="highlight">https://gitlab.example.com/api/v4/projects/123/pipeline</span> \
  --header <span class="highlight">'PRIVATE-TOKEN: glpat-xxxxxxxxxx'</span> \
  --form <span class="highlight">'ref=main'</span> \
  --form <span class="highlight">'variables[ENV]=production'</span>

Field	Description	Required
ref	Name of the branch or tag to run the pipeline on	Yes
variables	Array of variables to pass to the pipeline	No
yaml_errors	Return error if the YAML is invalid	No

Note: The PRIVATE-TOKEN must have api scope to trigger pipelines.

Example: Using GitLab API to Get Pipeline Status

const pipelineId = <span class="highlight">456</span>;
<span class="highlight">const projectId</span> = <span class="highlight">123</span>;

fetch(<span class="highlight">`https://gitlab.example.com/api/v4/projects/${projectId}/pipelines/${pipelineId}`</span>, {
  headers: {
    <span class="highlight">'PRIVATE-TOKEN'</span>: <span class="highlight">'glpat-xxxxxxxxxx'</span>
  }
})
.then(response => response.json())
.then(data => {
  console.log(<span class="highlight">'Pipeline Status:'</span>, data.status);
});

Custom Integration Best Practices

Use PRIVATE-TOKEN with minimal required scopes
Validate pipeline YAML before triggering to avoid runtime errors
Implement retry logic for API calls in case of transient failures
Log pipeline IDs for tracking and debugging

10. Using GraphQL API for CI/CD

Example: Query project pipelines

{% raw %}query {
  project(fullPath: "my-group/my-project") {
    pipelines(first: 5) {
      nodes {
        id
        status
        createdAt
        duration
      }
    }
  }
}{% endraw %}

Field	Description	Return Type
project(fullPath: String!)	Fetches a project by its full path	Project
pipelines(first: Int)	Retrieves a list of pipelines	PipelineConnection
nodes	Array of pipeline objects	[Pipeline]
id	Unique identifier for the pipeline	ID
status	Current status of the pipeline (running, success, failed)	PipelineStatus
createdAt	Timestamp when the pipeline was created	DateTime
duration	Duration of the pipeline in seconds	Int

Note: The GraphQL API for GitLab CI/CD is available starting from GitLab 15.0.

Example: Mutate pipeline variables

{% raw %}mutation {
  createPipelineVariable(
    input: {
      projectPath: "my-group/my-project"
      key: "DEPLOY_ENV"
      value: "staging"
    }
  ) {
    pipelineVariable {
      key
      value
    }
  }
}{% endraw %}

Field	Description	Return Type
createPipelineVariable(input: CreatePipelineVariableInput!)	Creates a new pipeline variable	CreatePipelineVariablePayload
projectPath	Full path of the project to set the variable in	String!
key	Name of the variable	String!
value	Value of the variable	String!

Warning: Ensure that sensitive data is not exposed in GraphQL queries or mutations. Use appropriate access controls and authentication.