Text of docs.gitlab.com › development › cicd as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

CI/CD development guidelines | GitLab Docs

/ CI/CD development guidelines CI/CD pipelines are a fundamental part of GitLab development and deployment processes, automating tasks like building, testing, and deploying code changes. When developing features that interact with or trigger pipelines, it’s essential to consider the broader implications these actions have on the system’s security and operational integrity. This document provides guidelines to help you develop features that use CI/CD pipelines securely and effectively.

It emphasizes the importance of understanding the implications of running pipelines, managing authentication tokens responsibly, and integrating security considerations from the beginning of the development process. General guidelines Recognize pipelines as write operations : Triggering a pipeline is a write operation that changes the system’s state. The write operation can initiate deployments, run tests, or alter configurations.

Treat pipeline triggers with the same caution as other critical write operations to prevent unauthorized changes or misuse of the system. Running a pipeline should be an explicit action : Actions that create a pipeline in the user’s context should be designed so that it is clear to the user that a pipeline (or single job) is started when performing the action. The user should be aware of the changes executed in the pipeline before they are executed.

Remote execution and isolation : The CI/CD pipeline functions as a remote execution environment where jobs can execute scripts performing a wide range of actions. Ensure that jobs are adequately isolated and do not unintentionally expose sensitive data or systems. Collaborate with AppSec and Verify teams : Include Application Security (AppSec) and Verify team members early in the design process and when drafting proposals.

Their expertise can help identify potential security risks and ensure that security considerations are integrated into the feature from the outset. Additionally, involve them in the code review process to benefit from their specialized knowledge in identifying vulnerabilities and ensuring compliance with security standards. Determine the pipeline actor : When building features that trigger pipelines, it’s crucial to consider which user initiates the pipeline.

You need to determine who should be the actor of the event. Is it an intentional pipeline run where a user directly triggers the pipeline (for example by pushing changes to the repository or clicking the “Run pipeline” button), or is it a pipeline run initiated by the GitLab system or a policy? Avoid scenarios in which the user creating the pipeline is not the author of the changes. If the users are not the same, there is a risk that the author of the changes can run code in the context of the pipeline user.

Understanding the actor helps in managing permissions and ensuring that the pipeline runs in the correct execution context. Variability of job execution users : The user running a specific job might not be the same user who created the pipeline. While in the majority of cases the user is the same, there are scenarios where the user of the job changes, for example when running a manual job or retrying a job. This variability can affect permissions and access levels in the job’s execution context.

Always account for this possibility when developing features that use the CI/CD job token ( CI_JOB_TOKEN ). Consider whether the job user should change and who the actor of the action is. Restrict scope of the operation : When enabling a new endpoint for use with the CI/CD job token, strongly consider limiting operations to the same job, pipeline, or project to enhance security. Strongly prefer the smaller scope (job) over larger scope (project).

For example, if allowing access to pipeline data, restrict it to the current pipeline to prevent cross-project or cross-pipeline data exposure. Evaluate whether cross-project or cross-pipeline access is truly necessary for the feature; limiting the scope reduces security risks. Monitor and audit activities : Ensure that the feature is auditable and monitorable. Introduce detailed logs of events that would trigger a pipeline, including the pipeline user, the actor initiating the action, and event details.

Other guides Development guides that are specific to CI/CD are listed here: If you are creating new CI/CD templates, read the development guide for GitLab CI/CD templates . If you are adding a new keyword or changing the CI schema, refer to the following guides: The CI configuration guide The CI schema guide If you are making a change to core CI/CD process such as linting or pipeline creation, refer to the CI/CD testing guide See the CI/CD YAML reference documentation guide to learn how to update the CI/CD YAML syntax reference page .

Metrics This section describes the dashboards and metrics that can be used by engineers during development, change validation and incident investigation. Dashboards for all GitLab teams are available. You can search for the team that owns the feature category you are interested in. The Pipeline Execution error budget dashboard contains other useful metrics about pipeline creation and job execution. Production logs also offer a lot of useful information that can be searched and aggregated in Kibana.

The Pipeline creation dashboard provides useful breakdowns of the steps involved in the pipeline creation. Note that this dashboard only contains data of “slow pipelines”, those that take longer to be created or have many jobs in them. It’s similar to a SQL “slow query log”. The CI partitioning dashboard contains information about the current partition number, partition sizes, vacuuming, and other database metrics.

Examples of CI/CD usage We maintain a ci-sample-projects group, with projects that showcase examples of .gitlab-ci.yml for different use cases of GitLab CI/CD. They also cover specific syntax that could be used for different scenarios. CI Architecture overview The following is a simplified diagram of the CI architecture. Some details are left out to focus on the main components. On the left side we have the events that can trigger a pipeline based on various events (triggered by a user or automation): A git push is the most common event that triggers a pipeline.

The Web API . A user selecting the “Run pipeline” button in the UI. When a merge request is created or updated . When an MR is added to a Merge Train . A scheduled pipeline . When project is subscribed to an upstream project . When Auto DevOps is enabled. When GitHub integration is used with external pull requests . When an upstream pipeline contains a trigger job which triggers a downstream pipeline. Triggering any of these events invokes the CreatePipelineService which takes as input event data and the user triggering it, then attempts to create a pipeline.

The CreatePipelineService relies heavily on the YAML Processor component, which is responsible for taking in a YAML blob as input and returns the abstract data structure of a pipeline (including stages and all jobs). This component also validates the structure of the YAML while processing it, and returns any syntax or semantic errors. The YAML Processor component is where we define all the keywords available to structure a pipeline.

The CreatePipelineService receives the abstract data structure returned by the YAML Processor , which then converts it to persisted models (like pipeline, stages, and jobs). After that, the pipeline is ready to be processed. Processing a pipeline means running the jobs in order of execution (stage or needs ) until either one of the following: All expected jobs have been executed. Failures interrupt the pipeline execution.

The component that processes a pipeline is ProcessPipelineService which handles: Setting jobs to their initial states of pending if they’re ready to run or created if they’re waiting on dependent jobs Updating jobs to pending based on recently completed depe

The rest of this page is on the live site.