ghaymah-exam-noran-sre/q3-cicd/README.md

# CI/CD Pipeline Documentation

This document describes the Continuous Integration and Continuous Deployment (CI/CD) pipeline implemented for the Ghaymah SRE exam.

---

# Pipeline Overview

The pipeline automates the application delivery process by:

1. Building a Docker image.
2. Pushing the image to the Ghaymah Container Registry.
3. Deploying automatically to the **Staging** environment.
4. Waiting for **manual approval**.
5. Deploying the same image to **Production**.

```
Developer Push
      │
      ▼
GitHub Actions
      │
      ▼
Build Docker Image
      │
      ▼
Push to Ghaymah Container Registry
      │
      ▼
Deploy to Staging
      │
      ▼
Manual Approval
      │
      ▼
Deploy to Production
```

---

# Manual Approval for Production

Production deployments are protected using **GitHub Environments**.

## Configuration

1. Open the repository.

2. Navigate to:

```
Settings
→ Environments
```

3. Create an environment named:

```
production
```

4. Enable:

- Required reviewers
- (Optional) Wait timer
- (Optional) Deployment branch restrictions

---

## Deployment Flow

After the application is successfully deployed to **Staging**, the workflow pauses before deploying to **Production**.

```
Build
   │
Deploy Staging
   │
Waiting for Approval
   │
Reviewer Approves
   │
Deploy Production
```

Only authorized reviewers can approve the deployment.

---

## Benefits

- Prevents accidental deployments.
- Adds an approval gate before production.
- Provides a complete audit trail.
- Supports controlled production releases.

---

# Staging vs Production

| Feature | Staging | Production |
|----------|----------|------------|
| Purpose | Integration testing and QA | Live customer environment |
| Users | Developers & QA | End users |
| Data | Test or sanitized data | Real production data |
| Replicas | Usually 1 | Usually 3 or more |
| Resources | Lower CPU/Memory | Higher CPU/Memory |
| Secrets | Test credentials | Production credentials |
| Deployment | Automatic | Manual approval required |
| Monitoring | Basic monitoring | Full monitoring and alerting |
| Rollback | Low impact | Carefully managed |
| Domain | staging.example.com | api.example.com |
| Logging | Verbose | Optimized for production |

> **Best Practice**
>
> The **same Docker image** (identified by its commit SHA) should be promoted from **Staging** to **Production**. Rebuilding the image for Production should be avoided to guarantee consistency.

---

# Ghaymah CLI Integration

> **Note**
>
> The official Ghaymah CLI documentation was not provided with the exam. The following commands are **placeholders** and should be replaced with the official syntax when available.

---

## 1. Install CLI

```bash
curl -sSL https://get.ghaymah.systems/cli/install.sh | sh

export PATH="$HOME/.ghaymah/bin:$PATH"
```

---

## 2. Authenticate

```bash
ghaymah login --token $GHAYMAH_TOKEN
```

Authentication credentials should be stored securely using GitHub Secrets.

---

## 3. Deploy Application

```bash
ghaymah deploy \
  --image registry.ghaymah.systems/ghaymah-api:latest \
  --name api-production \
  --port 5000 \
  --env FLASK_ENV=production \
  --replicas 3 \
  --health-check /health
```

---

## 4. Verify Deployment

```bash
ghaymah status --name api-production

ghaymah logs --name api-production
```

---

## 5. Scale Application

```bash
ghaymah scale \
  --name api-production \
  --replicas 5
```

---

## 6. Rollback

```bash
ghaymah deploy \
  --image registry.ghaymah.systems/ghaymah-api:<previous-tag> \
  --name api-production \
  --port 5000
```

---

# GitHub Secrets

Sensitive information should **never** be stored in the repository.

Configure the following repository secrets:

| Secret | Description |
|---------|-------------|
| `GHAYMAH_USERNAME` | Container Registry username |
| `GHAYMAH_TOKEN` | Access token used for authentication |

These secrets are referenced in the workflow as:

```yaml
${{ secrets.GHAYMAH_USERNAME }}

${{ secrets.GHAYMAH_TOKEN }}
```

---

# Best Practices

- Build the Docker image once and promote the same image between environments.
- Tag every image with the Git commit SHA for traceability.
- Keep secrets in **GitHub Secrets**, never in source code.
- Protect Production using **GitHub Environment approvals**.
- Enable Docker Buildx cache to reduce build time.
- Use health checks before considering a deployment successful.
- Maintain separate configurations for Staging and Production.
- Document deployment and rollback procedures.
- Monitor deployments and configure alerting for failures.

---

# References

- GitHub Actions Documentation
- Docker Buildx Documentation
- GitHub Environments Documentation

> Ghaymah CLI commands in this document are provided as implementation placeholders because the official CLI documentation was not included with the exam.