GitLab CI YAML Syntax

# CHAPTER 3

GitLab CI YAML Syntax #

1. Introduction #

2. Learning Objectives #

• Understand the strict formatting rules of YAML.

• Create a .gitlab-ci.yml file.

• Define custom stages globally.

• Write a job and assign it to a specific stage.

• Write terminal commands using the script keyword.

3. Beginner Explanation #

• You cannot just write: "Make a cake." The robot won't understand.

• You must write a highly structured, bulleted list.

• Stage: Baking

• Job: Mix Ingredients

• Step 1: Put 2 cups of flour in the bowl.

• Step 2: Add 1 cup of sugar.

• Step 3: Turn on mixer.

YAML (YAML Ain't Markup Language) is simply a way to write these bulleted lists so that a computer can read them perfectly without getting confused.

4. The .gitlab-ci.yml File #

The Golden Rules of YAML:

1. 1. Spaces, Not Tabs: YAML uses indentation to understand hierarchy. You MUST use spaces (usually 2 spaces per level). If you use the Tab key, the pipeline will crash instantly.

1. 2. Key-Value Pairs: It works like a dictionary: key: value.

5. Writing Your First Pipeline #

# 1. Define the chronological order of stages
stages:
  - build
  - test
  - deploy

# 2. Define Job 1
compile_code_job:
  stage: build              # Tells GitLab which stage this job belongs to
  script:                   # The actual terminal commands the Runner will execute
    - echo "Compiling the code..."
    - echo "Build successful!"

# 3. Define Job 2
security_scan_job:
  stage: test
  script:
    - echo "Running automated security tests..."
    - echo "No vulnerabilities found."

# 4. Define Job 3
deploy_to_server_job:
  stage: deploy
  script:
    - echo "Deploying code to the production server..."
    - echo "Deployment complete!"

6. Mini Project: Create Basic CI Workflow #

Step-by-Step Walkthrough:

1. 1. Open your terminal and clone your gitlab-ci-practice repository to your local machine.

1. 2. Navigate into the folder: cd gitlab-ci-practice

1. 3. Create the configuration file: touch .gitlab-ci.yml

1. 4. Open the file in your code editor (like VS Code).

1. 5. Paste the exact YAML code from Section 5 above into the file. Save it.

1. 6. Commit and push the code:

   git add .gitlab-ci.yml
   git commit -m "Add basic CI pipeline configuration"
   git push origin main
   ```
7. **The Magic:** Go to your repository on GitLab.com. Click **Build** -> **Pipelines**. 
8. You will see a blue "Running" status! Click on the pipeline. You will visually see the three stages (Build, Test, Deploy) executing one after another. Click on a specific Job bubble to see a live terminal output of your `echo` commands.

### 7. Variables in GitLab CI
Hardcoding values into your YAML file is bad practice. Instead, we use Variables.

yaml variables: # This variable is available to ALL jobs in the pipeline WEBSITENAME: "My Awesome App"

deployjob: stage: deploy script:

• echo "Deploying $WEBSITE_NAME to the server!"

*Note: We will learn how to store secret variables (like passwords) securely in the GitLab UI in a later chapter.*

### 8. Best Practices
- **The CI Lint Tool:** Because YAML is so sensitive to spaces, you will make syntax errors. Before you commit your `.gitlab-ci.yml` file, go to GitLab -> **Build** -> **Pipelines**, and click the **CI Lint** button in the top right. You can paste your YAML code there, and GitLab will tell you if the formatting is mathematically correct before you push it.

### 9. Common Mistakes
- **Incorrect Stage Assignment:** If you write a job but forget to include the `stage:` keyword, GitLab will automatically assign it to the default `test` stage. This can cause jobs to run in an unpredictable order. Always explicitly define `stage: <name>` inside every single job block.

### 10. Exercises
1. Why is indentation critical in a YAML configuration file?
2. What keyword is used inside a Job block to define the actual terminal commands the Runner will execute?

### 11. FAQs
**Q: Can I run multiple terminal commands in one job?**
A: Yes! The `script:` keyword accepts an array (a list). You simply add a dash (`-`) for each new command.

yaml script:

• npm install

• npm run build

• npm test

13. Next Chapter Recommendation #