GitOps Workshop with Port.io Developer Portal

A comprehensive end-to-end GitOps demo showcasing modern DevOps practices with Argo CD, GitHub Actions, Kubernetes, and Port.io software catalog integration.

What This Demo Covers

Topic	Components
GitOps	Argo CD, Kustomize overlays, Git as source of truth
CI/CD	GitHub Actions for testing, building, releasing
Security	CodeQL, Trivy (SCA & container), Gitleaks
Developer Portal	Port.io blueprints, entities, scorecards, self-service
Local Dev	Minikube, Kind, Rancher Desktop, Docker Desktop

Repository Structure

├── app/                          # Demo Node.js/Express application
│   ├── src/index.js             # Main application
│   ├── test/app.test.js         # Unit tests
│   ├── Dockerfile               # Multi-stage container build
│   └── package.json
│
├── k8s/                          # Kubernetes manifests
│   ├── base/                    # Base deployment & service
│   └── overlays/
│       ├── dev/                 # Dev environment (1 replica)
│       └── prod/                # Prod environment (3 replicas)
│
├── argo/                         # Argo CD Application manifests
│   ├── app-dev.yaml
│   └── app-prod.yaml
│
├── port/                         # Port.io configuration
│   ├── blueprints/              # Entity schemas (7 blueprints)
│   ├── entities/                # Sample data (40+ entities)
│   ├── scorecards/              # Production readiness rules
│   └── actions/                 # Self-service actions (7 actions)
│
├── .github/workflows/            # GitHub Actions
│   ├── ci.yml                   # Test & build on PRs
│   ├── release.yml              # Build, push, bump manifests
│   ├── port-sync.yml            # Sync entities to Port
│   ├── security.yml             # Trivy & Gitleaks scans
│   ├── codeql.yml               # CodeQL analysis
│   ├── deploy.yml               # Port self-service deploy
│   ├── scale.yml                # Port self-service scale
│   ├── rollback.yml             # Port self-service rollback
│   ├── restart.yml              # Port self-service restart
│   └── scaffold-service.yml     # Port self-service new service
│
└── docs/
    └── LOCAL_SETUP.md           # Local Kubernetes setup guide

Port.io Software Catalog

Blueprints (Entity Types)

Blueprint	Description	Key Properties
Team	Engineering teams	name, slack_channel, oncall_schedule, manager
Environment	Deployment targets	type (dev/staging/prod), cluster, auto_deploy
Service	Microservices	language, tier, lifecycle, test_coverage, security_score
Deployment	Running instances	version, replicas, status, health_status
API	REST/GraphQL endpoints	type, authentication, rate_limit, deprecation_date
Library	Shared packages	language, package_manager, is_internal
Cluster	K8s clusters	provider, kubernetes_version, ingress_controller

Entity Relationships

┌─────────┐      owns       ┌─────────────┐     provides    ┌───────┐
│  Team   │────────────────▶│   Service   │───────────────▶│  API  │
└─────────┘                 └─────────────┘                 └───────┘
     │                            │
     │                            │ deployed to
     │ maintains                  ▼
     │                      ┌─────────────┐
     │                      │ Deployment  │
     │                      └─────────────┘
     │                            │
     ▼                            ▼
┌─────────┐                ┌─────────────┐
│ Library │                │ Environment │
└─────────┘                └─────────────┘

Sample Data Included

• 6 Teams: Platform, Commerce, Payments, Frontend, Data, Security
• 14 Services: user-service, auth-service, order-service, payment-gateway, etc.
• 3 Environments: Development, Staging, Production
• 8 Deployments: Service instances across environments
• 6 APIs: REST and GraphQL endpoints
• 4 Libraries: Internal shared packages
• 1 Cluster: Local development cluster

Scorecards

Scorecard	Blueprint	Rules
Production Readiness	Service	Documentation, runbook, test coverage (60%+, 80%+), security score, PagerDuty, SLO target
Deployment Health	Deployment	Running status, healthy, multiple replicas, resource limits
API Maturity	API	Documentation, OpenAPI spec, authentication, rate limiting
Team Maturity	Team	Slack channel, email, on-call schedule, manager, cost center

Self-Service Actions

Action	Blueprint	Description
Deploy Service	Deployment	Deploy a service to an environment
Scale Service	Deployment	Scale replicas up or down
Rollback Deployment	Deployment	Rollback to a previous version
Restart Service	Deployment	Rolling restart of pods
Promote to Prod	Deployment	Promote staging to production (with approval)
Create New Service	Service	Scaffold a new microservice from template
Run Security Scan	Service	Trigger a security scan on demand

Quick Start

Prerequisites

• Git
• Docker
• kubectl
• Local Kubernetes (see docs/LOCAL_SETUP.md)
• Port.io account (sign up free)

1. Clone and Setup

git clone https://github.com/kunalnano/gitops-port.git
cd gitops-port

2. Start Local Kubernetes

# Using Minikube (recommended)
minikube start --cpus=4 --memory=8192
minikube addons enable ingress

3. Install Argo CD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for Argo CD
kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd

# Get password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

4. Deploy Applications

kubectl apply -f argo/app-dev.yaml
kubectl apply -f argo/app-prod.yaml

5. Access Argo CD

kubectl port-forward svc/argocd-server -n argocd 8080:443
# Open https://localhost:8080 (admin / <password from step 3>)

6. Configure Port.io

Add GitHub secrets:

• PORT_CLIENT_ID
• PORT_CLIENT_SECRET
• PORT_BASE_URL (default: https://api.getport.io)

Then trigger the Port Sync workflow manually or push changes to sync entities.

Workshop Scenarios

Scenario 1: Visualize Your Catalog

1. Open Port.io dashboard
2. View service dependencies graph
3. Filter services by team, tier, or lifecycle
4. Check scorecard compliance across services

Scenario 2: Deploy via Self-Service

1. In Port, navigate to a deployment entity
2. Click "Deploy Service" action
3. Select environment and image tag
4. Watch GitHub Action execute
5. See deployment status update in Port

Scenario 3: Production Readiness Review

1. View the Production Readiness scorecard
2. Identify services missing documentation or runbooks
3. Check which services have low test coverage
4. See security scores across all services

Scenario 4: Scaffold New Service

1. Click "Create New Service" action
2. Fill in: name, type, language, owner team
3. GitHub Action creates PR with:
   • Service directory structure
   • Kubernetes manifests
   • Port entity

Scenario 5: Incident Response

1. View degraded deployments in Port
2. Use "Restart Service" action
3. Or "Rollback Deployment" to previous version
4. Track action execution in real-time

CI/CD Pipeline

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Push   │────▶│   CI    │────▶│ Release │────▶│ GitOps  │
│  Code   │     │  Test   │     │  Build  │     │  Sync   │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
                    │               │               │
                    ▼               ▼               ▼
              ┌─────────┐     ┌─────────┐     ┌─────────┐
              │ CodeQL  │     │  GHCR   │     │ Argo CD │
              │ Trivy   │     │  Push   │     │  Sync   │
              └─────────┘     └─────────┘     └─────────┘
                                   │
                                   ▼
                             ┌─────────┐
                             │ Bump    │
                             │ Image   │
                             │ PR      │
                             └─────────┘

Security Features

• CodeQL: JavaScript security analysis
• Trivy FS: Dependency vulnerability scanning
• Trivy Image: Container image scanning
• Gitleaks: Secret detection
• Dependabot: Automated dependency updates

Best Practices Demonstrated

1. Immutable Images: Tags with commit SHA
2. GitOps Source of Truth: All changes via Git
3. Environment Parity: Kustomize overlays
4. Self-Healing: Argo CD auto-sync with prune
5. Security by Default: Scans on every PR
6. Developer Self-Service: Port actions for common tasks
7. Production Readiness: Scorecards enforce standards

Local Development

# Run the demo app locally
cd app && npm install && npm start
# Visit http://localhost:3000 and /healthz

# Run tests
npm test

Links

• Port.io Documentation
• Argo CD Documentation
• Kustomize Documentation
• Local Setup Guide

License

MIT