This repository provides a step-by-step guide to creating and managing a GitLab CI/CD pipeline for deploying applications. It covers everything from setting up the GitLab project, configuring runners, building Docker images, and deploying to production environments. Ideal for developers and DevOps engineers looking to automate their deployment workflow efficiently.
📘 Table of Contents
-
☁️ Create GitLab directory/repository
- Step 1 – Create GitLab Account
- Step 2 – Create a New Project
- Step 3 – Initialize Local Repository
- Step 4 – Link Repository and Push Code
- Step 5 – Provision EC2 Instance with Terraform
- Step 6 – Install GitLab Runner
- Step 7 – Register GitLab Runner
- Step 8 – Configure GitLab Runner User
- Step 9 – Docker Hub Authentication
This section explains how to set up AWS CLI authentication using IAM (Identity and Access Management), allowing secure command-line access to your AWS resources.
Click to show details
Install and configure the AWS Command Line Interface (AWS CLI) — a unified tool that enables you to manage AWS services directly from your terminal.
Click to show details
- In the AWS Management Console, navigate to IAM (Identity and Access Management).
- On the sidebar, select Groups → Create Group.
- Name the group cli-users.
- Attach the AdministratorAccess policy (recommended only for testing environments).
- Click Create Group to finalize.
Click to show details
- Still inside IAM, go to Users → Add User.
- Set the username to lucasmarguaws.
- Select the Programmatic access option (for CLI access).
- Add the user to the previously created cli-users group.
- Click Create User to complete the process.
Click to show details
- After the user is created, click the username (lucasmarguaws) to view its details.
- Go to the Security credentials tab.
- Click Create access key and choose the Command Line Interface (CLI) usage type.
- Copy and securely store the Access Key ID and Secret Access Key — they will be required for AWS CLI authentication.
Click to show details
Open your terminal or Command Prompt and run:
aws configureProvide your credentials when prompted:
AWS Access Key ID [None]: <your-access-key-id>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: us-east-1
Default output format [None]: jsonClick to show details
✅ Once completed, your AWS CLI is fully authenticated and ready to execute AWS commands or apply Terraform scripts securely and automatically.
This section describes how to create a Key Pair in AWS to enable secure SSH access to your EC2 instance.
Click to show details
- Open the AWS Management Console.
- Navigate to the EC2 service.
- In the left navigation pane, go to Key Pairs under Network & Security.
- Click Create key pair.
- In the Name field, enter: Terraform.
- Under File format, select .ppk (for PuTTY).
- Click Create key pair.
- Your browser will automatically download the file Terraform.ppk.
💾 Save it in a secure location, for example:
C:\Users<YourUser>.ssh\Terraform.ppk
✅ This key pair will later be referenced in Terraform to allow SSH access to the EC2 instance.
GitLab is an all-in-one DevOps platform offering:
- Version Control: Git-based versioning system.
- Continuous Integration (CI): Automates build, test, and deployment of code on every change.
- Continuous Delivery (CD): Automates deployment to testing, staging, and production environments reliably and consistently.
- Issue Tracking: Manage issues and tasks for progress monitoring.
- Team Collaboration: Unified platform for development, testing, and delivery, improving efficiency and reducing errors.
Our goal is to publish code, build containers, and deploy them to a Kubernetes cluster automatically.
Click to show details
- Visit GitLab
- Sign up for a free account or log in if you already have one.
- Click New Project
- Select Blank Project
- Set the project name and click Create Project
- After creation, GitLab will display instructions to initialize a local repository.
Click to show details
- Create a local directory for your project:
mkdir bootcampt-devops-project-1
cd bootcampt-devops-project-1Click to show details
- Initialize Git:
git init --initial-branch=main --object-format=sha1
- Configure local user information:
git config --local user.name "Your Name"
git config --local user.email "your.email@example.com"
- Add the GitLab remote repository:
git remote add origin git@gitlab.com:lucasmargui/bootcampt-devops-project-1.git
- Stage files for commit:
git add .
- Make the initial commit:
git commit -m "Initial commit"
- Push the code to GitLab:
git push --set-upstream origin main
- Reuse the existing bootcampt-devops-project-1 to configure a terraform and create a new EC2 instance for your GitLab Runner.
Click to show details
- Initialize Terraform:
terraform init- Apply the Terraform plan to create the EC2 instance:
terraform apply- After the instance is created, connect via SSH using PuTTY:
- Username: ubuntu
- Private Key: The one created previously (Terraform.ppk)
Click to show details
- SSH into your EC2 instance.
- Install GitLab Runner
Click to show details
Click to show details
Click to show details
sudo apt-get update
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner
- Confirm installation by pressing Enter when prompted. Note: You can also pre-install GitLab Runner in the Terraform configuration.
- In GitLab, navigate to your project: Settings > CI/CD > Runners > New Project Runner
Click to show details
- Copy the registration token from the three dots menu.
Click to show details
- On your EC2 instance, register the runner:
sudo gitlab-runner register
- GitLab instance URL: https://gitlab.com/
- Registration token: Copy from GitLab
- Runner tags: shell (or any tags you prefer)
Click to show details
- Your runner is now registered and ready to receive jobs
Click to show details
- GitLab Runner creates a user called gitlab-runner. Verify in:
cat /etc/passwd | grep gitlab-runner
- Add the runner to the Docker group to allow building and running containers:
sudo usermod -aG docker gitlab-runner
- Switch to root user (if needed, set a root password first):
sudo passwd root
su
- Set a password for gitlab-runner:
passwd gitlab-runner
- Switch to the gitlab-runner user:
su gitlab-runner
- Log in to Docker Hub (or company Docker registry):
docker login -u "your-username"
Click to show details
Click to show details
- Create a
.gitignorefile at the root of the repository. - Add files and directories that should not be versioned, such as Terraform state files or logs.
.terraform*
terraform*
Inside your application directory, create a Dockerfile.
This file will be used to build the container image.
Minimal example:
FROM httpd:latest
WORKDIR /usr/local/apache2/htdocs/
COPY * /usr/local/apache2/htdocs/
EXPOSE 80Click to show details
Create a .gitlab-ci.yml file at the root of the repository.
Divide the pipeline into stages (main sections) and jobs (tasks inside stages).
stages:
- build
- deploy
variables:
GLOBAL_VAR: "2.0"
Click to show details
- Job to build and push the Docker image:
criar_imagens:
stage: build
tags:
- aws
script:
- docker build -t lucasmargui/app-bootcamp-devops:$GLOBAL_VAR app/.
- docker push lucasmargui/app-bootcamp-devops:$GLOBAL_VAR
- Stage: build
- This job is part of the build stage in the CI/CD pipeline.
- Tags: aws
- Specifies that this job should run on runners tagged with aws (created in e2c).
- Script:
-
docker build -t lucasmargui/app-bootcamp-devops:$GLOBAL_VAR app/ Builds a Docker image using the Dockerfile located in the app/ directory. The image name will be lucasmargui/app-bootcamp-devops and the tag will be set using the environment variable $GLOBAL_VAR.
-
docker push lucasmargui/app-bootcamp-devops:$GLOBAL_VAR Pushes the built Docker image to the remote Docker repository.
Click to show details
- Add and commit the new files:
git add .
git commit -m "Create CI/CD Pipeline"
git push --set-upstream origin main
- Job to run the container on the production server:
executar_imagens:
stage: deploy
needs:
- criar_imagens
tags:
- aws
before_script:
- docker rm $(docker ps -a -q) --force
script:
- docker run -dti --name web-server -p 80:80 lucasmargui/app-bootcamp-devops:$GLOBAL_VAR
after_script:
- docker system prune --force
- Stage: deploy
- This job runs in the deploy stage of the CI/CD pipeline.
- Dependencies: needs: criar_imagens
- Ensures this job only runs after the criar_imagens job has successfully completed.
- Tags: aws
- Specifies that this job should run on runners tagged with aws.
- Before Script:
docker rm $(docker ps -a -q) --force
- Removes all existing Docker containers to ensure a clean environment before starting the new container.
- Script:
docker run -dti --name web-server -p 80:80 lucasmargui/app-bootcamp-devops:$GLOBAL_VAR
- Runs the Docker image in a detached and interactive terminal mode.
- Names the container web-server
- Maps port 80 on the host to port 80 in the container
- Uses the image lucasmargui/app-bootcamp-devops with the tag $GLOBAL_VAR.
- After Script:
docker system prune --force
- Cleans up unused Docker objects to free disk space and keep the environment tidy.
Click to show details
- Add, commit, and push:
git add .
git commit -m "Deploy container"
git push
- Verify in GitLab that the container is running successfully.
To update the application (e.g., version 2.0 → 3.0):
variables:
GLOBAL_VAR: "3.0"
Click to show details
