The ability to rerun pipelines within GitLab is a critical component of a robust continuous integration and continuous deployment (CI/CD) strategy. Whether dealing with flaky tests, environment instabilities, or the need for manual deployment triggers, understanding the mechanisms for re-executing jobs and entire pipelines ensures that software delivery remains fluid and reliable. In a professional DevOps environment, a "rerun" is not merely a repetitive action but a strategic response to failure or a requirement for validation. This process can range from using high-level third-party integrations like BrowserStack to direct manipulation of the GitLab REST API or adjusting project-level settings to manage pipeline redundancy and visibility.
Integration of BrowserStack for Automated Test Reruns
Integrating external test reporting and analytics tools can significantly streamline the feedback loop when dealing with failed test cases. BrowserStack provides a specialized integration for GitLab that allows users to trigger reruns of failed tests directly from a dashboard, effectively bypassing the need to manually navigate to the GitLab UI to trigger a new pipeline.
The implementation of this functionality requires a specific handshake between the BrowserStack dashboard and the GitLab environment.
To enable pipeline triggers for reruns, each individual user must complete a configuration process:
- Open the integration page: Configure GitLab integration.
- Create a GitLab personal access token (PAT): Navigate to User > Preferences > Access Tokens > Add new token.
- Define the token parameters: Set an expiry date and select the minimal scope required. The recommended scope for triggering pipelines is
api. - Submit the token: Enter the PAT into the BrowserStack form and select Submit.
- Audit token scopes: Review the assigned permissions and remove any unnecessary scopes to adhere to the principle of least privilege.
Once the integration is configured, the actual triggering of a rerun occurs within the BrowserStack Test listing. When a user hovers over a failed test name, a rerun icon becomes available. Selecting this icon initiates the pipeline trigger in GitLab.
This capability has a profound impact on the developer experience. By removing the requirement to manually trigger pipelines via the GitLab interface, the time between identifying a failure and validating a fix is drastically reduced. This creates a tighter loop between the Test Reporting & Analytics layer and the execution layer in GitLab.
In the context of the wider GitLab ecosystem, this integration relies on the .gitlab-ci.yml file. For these reruns to function, the configuration file in the target repository must be structured such that the jobs can be triggered via the API.
Manual Job Triggers and Pipeline-Level Reruns
A common challenge for DevOps engineers is the distinction between rerunning a single job and rerunning an entire pipeline. In standard GitLab behavior, clicking a button for a manual deployment job only executes that specific job and any jobs that depend on it, rather than restarting the full pipeline from the beginning.
For users operating on self-hosted GitLab versions, such as version 15.9.2, the limitation of the manual button is evident. Standard attempts to resolve this using needs relationships or child pipelines often fail to produce a full pipeline rerun. Specifically, attempting to define the environment only for the trigger job within a child pipeline is forbidden.
The only viable technical workaround for achieving a full pipeline rerun via a manual button is to have that manual job call the GitLab API. By utilizing a script within the manual job that sends a request to the Pipelines API, a user can programmatically trigger a new pipeline instance.
This architectural constraint means that for "less technical" colleagues to have a smooth deployment experience, the technical lead must wrap the API call within a job. This prevents the user from needing to understand the underlying API structures while still achieving the goal of a total pipeline restart.
The GitLab Pipelines API for Programmatic Control
The Pipelines API provides the fundamental mechanism for interacting with CI/CD pipelines at scale. This API is available across all tiers (Free, Premium, and Ultimate) and all offerings, including GitLab.com, GitLab Self-Managed, and GitLab Dedicated.
To programmatically manage or rerun pipelines, the GET /projects/:id/pipelines endpoint is used to list project pipelines. This is essential for identifying the most recent failed pipeline that requires a rerun.
The API supports several parameters to filter and organize the pipeline data:
- id: The ID or URL-encoded path of the project (Required).
- name: Return pipelines with a specific name.
- orderby: Order results by id, status, ref, updatedat, or user_id.
- ref: Filter by a specific branch or tag.
- scope: Filter by running, pending, finished, branches, or tags.
- sha: Filter by the specific commit SHA.
- sort: Set the order to asc or desc.
- source: Filter by the source of the pipeline. This is critical for child pipelines, as they are not included by default unless the source is set to
parent_pipeline. - status: Filter by created, waitingforresource, preparing, pending, running, success, failed, canceled, skipped, manual, or scheduled.
- updated_after: Filter pipelines updated after a specific ISO 8601 date (e.g.,
2019-03-15T08:00:00Z).
Using these API endpoints allows for the creation of custom automation scripts that can detect a "failed" status and automatically trigger a rerun, or allow a manual job to trigger a fresh pipeline run by referencing the current commit SHA.
Advanced Pipeline Settings and Configuration
Managing the lifecycle of pipelines involves more than just starting and restarting them; it requires controlling visibility, redundancy, and resource cleanup. These settings are managed within the project's CI/CD configuration.
Pipeline Visibility and Access Control
The visibility of pipelines affects who can view job output logs, artifacts, and security results. This is configured via Settings > CI/CD > General pipelines.
When the Project-based pipeline visibility checkbox is selected:
- Public projects: Everyone can view.
- Internal projects: All authenticated users (except external users) can view.
- Private projects: All project members with Guest role or higher can view.
When this checkbox is cleared, the restrictions become more stringent:
- Public projects: Job logs, artifacts, and the security dashboard are only visible to project members with Reporter role or higher. Guest users can only see the status of pipelines/jobs when viewing commits or merge requests.
- Internal projects: Pipelines remain visible to all authenticated users except external users.
Managing Pipeline Redundancy and Safety
To optimize resource usage and prevent deployment errors, GitLab provides several specialized settings:
Auto-cancel redundant pipelines: This feature, found in Settings > CI/CD > General Pipelines, prevents multiple pipelines from running on the same ref if a newer commit has been pushed. To refine this, the interruptible keyword is used in the .gitlab-ci.yml file. If a job is marked as interruptible: false, the entire pipeline is no longer considered interruptible once that job begins.
Preventing outdated deployment jobs: In scenarios where multiple concurrent deployment jobs are scheduled, there is a risk that an older job could complete after a newer one, leading to a version mismatch in production. This is mitigated by selecting the Prevent outdated deployment jobs checkbox in the General pipelines settings. Users may also choose to clear the Allow job retries for rollback deployments checkbox to further restrict behavior.
Pipeline Storage and Cleanup
To maintain system performance and manage storage, Owners can configure automatic pipeline cleanup. This is done by entering a value (in seconds or human-readable format, such as 2 weeks) in the Automatic pipeline cleanup field. The system then automatically deletes pipelines older than this value. The range must be between one day and one year.
GitLab Runner Command Line Operations
While pipeline reruns are typically handled via the UI or API, the underlying execution is managed by the GitLab Runner. Understanding the runner's command-line interface is essential for troubleshooting the environment where reruns occur.
The gitlab-runner tool provides various commands and supports specific signals for process management.
| Command | Signal | Action |
|---|---|---|
| register | SIGINT | Cancel runner registration and delete if already registered |
| run, run-single | SIGINT, SIGTERM | Abort all running builds and exit as soon as possible |
| run, run-single | SIGQUIT | Stop accepting new builds; exit after current builds finish |
| run | SIGHUP | Force reload of the configuration file |
For administrators managing self-hosted runners, the following commands are used for process control:
To reload the configuration:
sudo kill -SIGHUP <main_runner_pid>
For a graceful shutdown:
sudo kill -SIGQUIT <main_runner_pid>
It is critical to avoid using killall or pkill for graceful shutdowns, especially when using shell or docker executors. Doing so can lead to the improper handling of signals because sub-processes may be killed prematurely.
Conclusion
The process of rerunning pipelines in GitLab is a multifaceted operation that spans from the high-level integration of third-party analytics tools to the low-level management of runner signals. For the end-user, tools like BrowserStack provide a seamless "one-click" rerun experience by leveraging Personal Access Tokens and the GitLab API. For the DevOps engineer, the challenge lies in bridging the gap between manual job triggers and full pipeline execution, a gap that can only be closed through programmatic interaction with the Pipelines API.
The stability of these reruns is further supported by strategic project settings. By implementing automatic pipeline cleanup and preventing outdated deployments, organizations ensure that their CI/CD environment remains performant and predictable. Furthermore, the use of the interruptible keyword and precise role-based access control for canceling pipelines allows for a balanced approach between agility and safety. Ultimately, the ability to precisely control, trigger, and clean up pipelines is what transforms a simple CI script into a professional-grade deployment pipeline.