Gitlab (Bonus)

Violet Streams • DevOps hands-on lab • Lab 6G

Your First GitLab CI/CD Pipeline
Build and Deploy to Tomcat

Start in the browser. Import the working Lab 6 application, add three variables, and deploy to your existing Tomcat server on port 8090.

BEGINNER WALKTHROUGH  |  HOSTED RUNNERS  |  BUILD → DEPLOY

What you will complete

A two-job pipeline: Maven builds MyWebApp.war; the next job uploads that file to your existing Tomcat server. There are no branch conditions, manual approvals, or custom deployment checks in the YAML. Your Tomcat installation is not changed.

Use the same working project, server, port, and Tomcat deployment credentials from Lab 6. You do not need to install GitLab, Maven, Java, Docker, or a runner on your laptop for this browser-based walkthrough.

Choose the right starting point

New to GitLab: follow all steps. The main route imports GitHub into GitLab once, then uses the GitLab copy for class.
Project already imported: sign in, open it, and begin at Step 3.
GitHub already connected for external CI/CD: keep that connection; do not create a duplicate import. Follow the GitHub-specific note in Step 7 for code changes.

Documentation: GitLab: your first CI/CD pipeline · GitLab: CI/CD for external repositories

Have this ready	Use your existing Lab 6 information
GitHub source repository	Your repository containing MyWebApp/pom.xml.
Build output	MyWebApp/target/MyWebApp.war; the project already builds with Java 21.
Tomcat address	http://YOUR-TOMCAT-IP:8090; use the public host name or IP supplied for your lab.
Tomcat credentials	The existing Manager deployment username and password. These are not your GitLab or GitHub login.
Access	Your own isolated lab project, or a project where your instructor grants the required Maintainer access.

Shared-server caution

Every branch pipeline with a successful build attempts to replace the same /MyWebApp application. Coordinate with classmates and do not run the old Jenkins deployment at the same time. Use lab-only credentials; HTTP on port 8090 does not encrypt them. For real deployments, use HTTPS.

Jump to a step

1. Create your GitLab account2. Import the GitHub project3. Find your way around the project4. Enable hosted runners5. Enter the three Tomcat variables6. Create the pipeline file7. Paste and commit the YAML8. Open the pipeline and build log9. Find the WAR artifact10. Read the deployment result11. Open your application12. Change the page and redeploy13. Run the pipeline again

Step 1 — Create your GitLab account

1. Open a browser tab and go to GitLab’s sign-up page.
2. Enter your first name, last name, a unique username, an email address you can access, and a password. Select Continue. Already registered? Select Sign in instead.
3. Open the verification email and complete the verification requested by GitLab. Return to the GitLab tab and finish any required onboarding prompts.
4. Use GitLab.com, not a self-managed installation. This import-and-build route does not need a Premium subscription.
5. Once signed in, keep this tab open. Use the top Search or go to bar whenever you need to find your project again.

Account verification

GitLab may also request phone or card verification. Follow only the prompts on the official GitLab site. A verification prompt is not an instruction to install a runner or automatically buy a subscription.

Documentation: GitLab sign-up page · GitLab: identity verification · GitLab: your first CI/CD pipeline

Step 2 — Import your working GitHub project

WHERE TO CLICKCreate new (+) → New project/repository → Import project → GitHub

1. In GitLab’s top bar, find the + / Create new menu, currently in the upper-right area. Choose New project/repository.
2. Choose Import project, then select GitHub. Do not choose a blank project or the external-repository option for this route.
3. Select Authorize with GitHub. Sign in to the GitHub account that owns or can access your Lab 6 repository, review the permissions, and authorize GitLab.
4. Back in GitLab, locate the correct repository. Set its destination namespace to your own account or the instructor-approved group. A namespace is the owner shown before the project name.
5. Use a project name such as mywebapp-gitlab-lab. If import options include collaborators, leave them out for an individual lab unless your instructor needs them.
6. Click Import beside that repository—not Import all repositories.
7. When the status shows Complete, click the new GitLab project path to open it. If the source is absent, confirm you authorized the correct GitHub account and have access to that repository.

From this point, edit the GitLab copy

This is a one-time import. Your GitHub repository is not deleted, but later GitHub changes do not automatically arrive here. Complete the remaining browser edits in GitLab. Ongoing GitHub mirroring/external CI is a separate setup.

Documentation: GitLab: import from GitHub · GitLab: CI/CD for external repositories

Step 3 — Find your way around the project

WHERE TO CLICKYour project → Code → Repository

1. Look for your project’s name at the top of the left sidebar. These instructions use project settings, not your profile settings or a group’s settings.
2. Expand Code in that sidebar, then choose Repository. The main panel shows your files and folders.
3. Find the branch selector above the file list. Leave the default branch selected. It may be main or master; do not rename it for this lab.
4. Click MyWebApp, then pom.xml to view the existing project. Do not replace the working POM.
5. Return to the top-level file list by clicking the project name in the file-path breadcrumb or selecting Code → Repository again.

Your project before adding the pipeline

repository-root/
└── MyWebApp/
    ├── pom.xml
    └── src/
        ├── main/
        └── test/

Menu	What you will use it for
Code → Repository	View files and make browser edits.
Settings → CI/CD	Find runners and enter the three variables.
Build → Pipelines	Open each pipeline and its job logs.
Build → Artifacts	Browse or download the generated WAR.

Missing Settings?

Confirm you opened the project rather than a group or your profile. Variable management requires Maintainer access. Ask your instructor for that access when using a shared project.

Documentation: GitLab: your first CI/CD pipeline · GitLab: CI/CD variables · GitLab: job artifacts

Step 4 — Enable GitLab-hosted runners

WHERE TO CLICKProject sidebar → Settings → CI/CD → Runners → Expand

1. Click Settings in the project’s left sidebar, then CI/CD.
2. Find the Runners section and click Expand.
3. In the instance-runner area, leave Turn on instance runners for this project enabled. Turn it on if it is off and you are allowed to change it.
4. Do not choose Create project runner. There is nothing to install or register.
5. Keep the supplied YAML untagged. GitLab’s hosted Linux runner will execute these jobs.

A runner is the machine that executes a job. The Maven container provides Java and Maven for the build; the Alpine container is used for deployment. You do not install either image on your computer.

A disabled toggle or verification banner

A parent group may control runner access. Ask the instructor to enable it at the group level when necessary. Complete any GitLab account-verification prompt before starting CI. Hosted compute usage is limited by the account or namespace plan.

Documentation: GitLab: enable instance runners · GitLab: hosted Linux runners · GitLab: identity verification

Step 5 — Enter the three Tomcat variables

WHERE TO CLICKProject sidebar → Settings → CI/CD → Variables → Expand → Add variable

Create each row below separately. Keep Type = Variable, Environment scope = All (*), and Expand variable reference = off. For this isolated, all-branch lab, leave Protect variable = off. Do not use this setting for shared production credentials.

1. Expand Variables, then click Add variable.
2. Copy the first row’s Key exactly. Enter only its value in Value; do not paste KEY=value or add quotation marks.
3. Select the listed Visibility and click Add variable to save.
4. Repeat for rows 2 and 3, using Add variable each time.

Row / Key	Value to enter	Visibility
1 — TOMCAT_URL	http://YOUR-TOMCAT-IP:8090 Replace the host with your server. No trailing slash, /manager, or /MyWebApp.	Visible
2 — TOMCAT_USER	Your existing Tomcat deployment username, for example tomcat.	Visible
3 — TOMCAT_PASSWORD	Your existing Tomcat deployment password. Do not enter a GitLab/GitHub password.	Masked and hidden

Password masking

Masked values must be one line, contain no spaces, and have at least eight characters. A short username such as tomcat is intentionally Visible. If the existing password cannot be masked, ask your instructor for a suitable lab password rather than exposing it.

Only three variables

Confirm the table contains TOMCAT_URL, TOMCAT_USER, and TOMCAT_PASSWORD. Do not create APP_DIR, WAR_FILE, or TOMCAT_CONTEXT. The paths are written directly in the YAML.

Documentation: GitLab: CI/CD variables

Step 6 — Create the pipeline file in GitLab

WHERE TO CLICKCode → Repository → Repository root → + → New file

1. Return to Code → Repository. Stay at the top-level file list, outside MyWebApp.
2. Leave the default branch selected in the branch dropdown.
3. Above the file list, click the + menu next to the directory/repository controls. Choose New file. This is the repository’s + menu, not the global menu for creating projects.
4. In Filename, enter exactly .gitlab-ci.yml. Include the first dot. Do not add .txt.
5. Click inside the large editing area. Paste the complete YAML from Step 7; use it instead of any suggested template.

Already have .gitlab-ci.yml?

Open that file at the repository root, select Edit → Edit single file, and replace its contents with Step 7. Do not create a second pipeline file.

Correct file location

repository-root/
├── .gitlab-ci.yml        ← Create the file here
└── MyWebApp/
    ├── pom.xml
    └── src/

Documentation: GitLab: your first CI/CD pipeline · GitLab: Web Editor

Step 7 — Paste the simple pipeline and commit it

Copy only the following YAML into the editor. Keep the indentation. Do not paste the Blogger HTML or Markdown backticks into GitLab.

.gitlab-ci.yml — copy the complete block

stages:
  - build
  - deploy

build:
  stage: build

  image: "maven:3.9.16-eclipse-temurin-21-noble"

  script:
    - mvn -B -ntp -f MyWebApp/pom.xml clean install

  artifacts:
    paths:
      - MyWebApp/target/MyWebApp.war

deploy:
  stage: deploy

  image: "alpine:3.22"

  needs:
    - job: build
      artifacts: true

  before_script:
    - apk add --no-cache curl

  script:
    - >
      curl
      --user "$TOMCAT_USER:$TOMCAT_PASSWORD"
      --upload-file MyWebApp/target/MyWebApp.war
      "${TOMCAT_URL}/manager/text/deploy?path=/MyWebApp&update=true"

The build runs the existing Maven goal, clean install. The artifact carries MyWebApp.war into the separate deploy job. update=true tells Tomcat to replace the existing application at /MyWebApp.

1. Click Commit changes. If a commit dialog opens, enter Add GitLab build and Tomcat deployment as the commit message.
2. Keep the current/default branch selected. Do not choose Commit to a new branch or create a merge request for this introductory run.
3. Confirm Commit changes in the dialog. Saving a commit in the browser already updates the remote repository; no terminal git push is needed.
4. You should return to the file view. The committed pipeline is now eligible to start.

Already using GitHub as the live source?

For an instructor-configured external-repository CI connection, create this file in the GitHub repository root using Add file → Create new file, then commit it there. Continue in GitLab for variables and job logs. Make the later page edit in GitHub too. Do not edit the mirrored copy in GitLab; a later sync can overwrite it.

Documentation: GitLab: your first CI/CD pipeline · GitLab: Web Editor · Docker Official Image: Maven · GitLab: job artifacts · Apache Tomcat: Manager text API · GitLab: CI/CD for external repositories

Step 8 — Open the pipeline and read the build log

WHERE TO CLICKProject sidebar → Build → Pipelines → Latest pipeline ID → build

1. Expand Build in the left sidebar. Click Pipelines.
2. Find the row with your latest commit message. Click its pipeline number/ID to open it.
3. The diagram contains build and deploy. Click the build job to open the scrolling log.
4. Follow Maven’s output. A successful build ends with BUILD SUCCESS and an artifact-upload message.
5. Click the pipeline ID/breadcrumb above the job to return to the diagram. Once the build succeeds, the deployment job can start.

Status	Meaning in this lab
Pending	The job is queued or waiting for an eligible runner.
Running	The runner is executing the job.
Passed	The job commands returned success. Read the deployment response in Step 10 too.
Failed	Open that job’s log and locate the first relevant error.
Skipped	The job did not run; for example, deployment is not run after a failed build.

If no pipeline appears, confirm the file is named .gitlab-ci.yml at the repository root and that the commit was saved. Use Step 13 to start the same configuration manually.

Documentation: GitLab: your first CI/CD pipeline · GitLab: start and view pipelines

Step 9 — Locate the generated WAR artifact

WHERE TO CLICKBuild → Pipelines → Your pipeline → build → Job artifacts → Browse

1. Open the completed build job.
2. Look in the job’s right-hand details area for its artifacts and select Browse. You can also use Build → Artifacts and open the build job’s artifact entry.
3. In the artifact browser, open MyWebApp, then target.
4. Find MyWebApp.war. Downloading it is optional; the deploy job retrieves it automatically.

Do not look for target in the source repository. It is generated during the job, not committed as source. The needs section downloads the build artifact into deployment’s separate workspace.

Documentation: GitLab: job artifacts · GitLab: hosted Linux runners

Step 10 — Read Tomcat’s deployment response

WHERE TO CLICKBuild → Pipelines → Your pipeline → deploy

1. Return to the pipeline diagram and click the deploy job.
2. In its log, locate the response printed after the curl command.
3. A successful Manager deployment normally prints a line beginning with OK. A line beginning with FAIL means Tomcat rejected it.
4. Continue to Step 11 to open the actual application. Do not treat the status badge alone as proof of deployment.

Illustrative Tomcat response

OK - Deployed application at context path /MyWebApp

Why you must read the response

This intentionally minimal pipeline does not check HTTP status codes, parse Tomcat’s response, or run a health check. Plain curl may exit successfully even after receiving an HTTP error page. A green job is therefore not sufficient evidence that the application was deployed.

Documentation: Apache Tomcat: Manager text API · curl: HTTP error handling

Step 11 — Open the deployed application

1. Open a separate browser tab.
2. In the address bar, type the URL below, replacing the placeholder with your existing Tomcat public host.
3. Press Enter. The Lab 6 web page should appear.
4. Keep the tab open for the next exercise. Retain the exact capitalization of MyWebApp.

Application URL — not the Manager URL

http://YOUR-TOMCAT-IP:8090/MyWebApp/

Use your application address here, not /manager/text/deploy. The Manager endpoint accepts the deployment; /MyWebApp/ is the page your visitors open.

Documentation: Apache Tomcat: Manager text API

Step 12 — Make a browser edit and redeploy

WHERE TO CLICKCode → Repository → MyWebApp → src → main → webapp → index.jsp → Edit → Edit single file

1. Return to GitLab and choose Code → Repository. Use the same branch as before.
2. Open MyWebApp → src → main → webapp → index.jsp.
3. At the file’s upper-right, select Edit → Edit single file.
4. Change only the visible heading to the sample below. Keep the rest of the existing page and JSP syntax intact.
5. Click Commit changes, enter Update home page from GitLab, and commit to the current branch.
6. Open Build → Pipelines. Open the new pipeline and follow both jobs as you did before.
7. Read the deploy response. Then refresh the application tab to see your new heading. If your browser shows the old page, try a hard refresh.

Edit the existing heading; do not replace the entire JSP

<h1>Hello from GitLab CI/CD!</h1>

Source repository reminder

After the one-time import, make this change in GitLab. With an already configured external GitHub CI integration, instead edit the same file in GitHub and watch its connected GitLab pipeline.

Documentation: GitLab: Web Editor · GitLab: CI/CD for external repositories

Step 13 — Run the pipeline again without editing code

WHERE TO CLICKBuild → Pipelines → New pipeline → Select branch → New pipeline

1. In the GitLab project, open Build → Pipelines.
2. Click New pipeline in the upper-right area of the page. Older layouts may call it Run pipeline.
3. In Run for branch name or tag, select the branch containing .gitlab-ci.yml.
4. Do not enter the Tomcat password on this page. The job already uses your saved project variables.
5. Click New pipeline to launch it. Open the pipeline ID, then each job log.

This also deploys

Starting a new pipeline reruns the build and then attempts deployment to the same application. There is no approval button or branch filter in this YAML. Do not start multiple runs against the shared Tomcat application at once.

Documentation: GitLab: start and view pipelines

When a student gets stuck

What you see	Where to go / what to check
No Settings or Add variable control	Confirm you are inside the project. Ask for Maintainer access rather than editing a group or profile.
Variable cannot be saved	Use Visible for the URL and username. A masked password must meet the masking requirements. Enter values without surrounding quotes or KEY=.
Job remains pending	Return to Settings → CI/CD → Runners. Check instance-runner availability, verification prompts, and account/namespace compute availability. Do not install a runner.
Build cannot find pom.xml	Open Code → Repository and confirm MyWebApp/pom.xml. This YAML assumes that exact existing Lab 6 layout.
Build fails	Open Build → Pipelines → pipeline ID → build. Read the Maven error, not only the final red status.
Empty or wrong Tomcat credential	Open Settings → CI/CD → Variables; choose Edit beside the relevant key, correct it, and save with Update variable. Then use Step 13. Never print passwords in a job log.
401, 403, timeout, or HTML error page	Recheck the saved URL and existing deployment credentials. A Jenkins connection working does not prove this separate hosted runner has the same network access. Ask the instructor to review access from GitLab; do not remove server restrictions blindly.
Green deploy job, unchanged application	Read the deploy log’s response and use the exact /MyWebApp/ application path. This pipeline does not automatically detect every Tomcat rejection.
Cannot commit to current branch	The imported branch may have protection rules. Ask your instructor for the correct lab permissions; do not remove shared-project protections.

Documentation: GitLab: CI/CD variables · GitLab: enable instance runners · GitLab: identity verification · GitLab: import from GitHub · curl: HTTP error handling

Lab completion evidence

Show your instructor the pipeline containing both jobs, the MyWebApp.war artifact, the Tomcat OK response, and the updated page at port 8090. Do not include passwords in screenshots.

The complete classroom workflow

Edit in GitLab → Commit → build → WAR artifact → deploy → Tomcat :8090/MyWebApp/

After class: remove or rotate temporary deployment credentials when they are no longer needed. Keep real production credentials restricted to trusted code and use HTTPS; this exercise intentionally omits production deployment controls.

Violet Streams Institute of Technology • Lab 6G • Navigation checked against official documentation on September 19, 2026. GitLab may move controls between releases; use the named project sections. This is a lab guide, not a record of a deployment performed on your server.