How To Run and Protect Manual Jobs on GitLab CI/CD Pipelines

GitLab CI/CD pipelines are an essential component of modern software development workflows, providing automation for building, testing, and deploying applications. However, there are scenarios where manual intervention is necessary, and GitLab allows you to create manual jobs within your pipelines. This article will guide you on how to run and protect manual jobs in GitLab CI/CD pipelines.

Understanding Manual Jobs in GitLab CI/CD

Manual jobs are those that require user intervention to execute. Unlike automated jobs that run automatically when triggered by events like code pushes or merge requests, manual jobs wait for a user to start them. They are useful in scenarios such as:

Deploying to production environments where human approval is required.
Running specific tests or scripts only in certain conditions.
Executing critical tasks that need careful oversight.

Setting Up Manual Jobs

To set up manual jobs in your GitLab CI/CD pipeline, you need to define them in the .gitlab-ci.yml file with the when: manual keyword.

Example Configuration

Here is a basic example of a .gitlab-ci.yml file with manual jobs:

In this configuration, deploy_staging and deploy_production are manual jobs that need to be triggered by a user.

Running Manual Jobs

To run manual jobs, follow these steps:

Navigate to the Pipeline: Go to your project in GitLab and click on "CI / CD" in the sidebar, then select "Pipelines."
View the Pipeline: Find the pipeline you want to run the manual job for and click on it.
Run the Manual Job: You will see the stages and jobs defined in the pipeline. Manual jobs will have a "Play" button next to them. Click the "Play" button to start the job.

Protecting Manual Jobs

Protecting manual jobs is crucial to ensure that only authorized personnel can trigger them, especially for sensitive tasks like deploying to production. GitLab provides several mechanisms to secure manual jobs.

Protected Branches and Tags

One of the primary ways to protect manual jobs is by using protected branches and tags. This ensures that only certain users can run jobs associated with protected branches or tags.

Protect a Branch:
- Go to your project in GitLab.
- Click on "Settings" in the sidebar, then "Repository."
- Scroll down to "Protected branches" and add the branch you want to protect.
- Define the allowed roles for pushing and merging.
Protect a Tag:
- In the same "Repository" settings, scroll to "Protected tags."
- Add the tag you want to protect and define the allowed roles.

Job-Level Protection

You can also protect jobs directly by specifying who can run them in the .gitlab-ci.yml file.

Using GitLab Permissions

GitLab allows you to assign different roles to users, such as Maintainer, Developer, Reporter, etc. You can control who has the permission to run manual jobs by assigning appropriate roles to team members.

Best Practices for Manual Jobs

Clear Documentation: Ensure that instructions for running manual jobs are well-documented and accessible to those who need to run them.
Notification and Approval: Set up notifications for when manual jobs need to be run, and if necessary, implement an approval process.
Security Audits: Regularly review who has access to run manual jobs and ensure that permissions are up-to-date.
Environment Segregation: Use separate environments for staging and production, and ensure that only approved personnel can deploy to production.

Conclusion

Manual jobs in GitLab CI/CD pipelines provide a flexible way to introduce human oversight into your automated workflows. By properly configuring and protecting these jobs, you can ensure that critical tasks are executed with the necessary approvals and security controls. Implementing these practices will help maintain the integrity and security of your CI/CD processes, allowing your team to deliver high-quality software efficiently.