DevOps Skills & Best Practices

DevOps standards, CI/CD pipelines, and containerization practices.

Table of Contents

• CI/CD
• Docker
• GitHub CLI (gh) for DevOps

---

CI/CD

GitHub Actions

Strict Requirements: When creating a Pull Request, the following checks MUST run and MUST pass before merging:

1. Security Checks (Strict)

   • Dependency vulnerability scanning
   • Use tools like pnpm audit, Dependabot, or Snyk

2. SonarQube Analysis (Strict)

   • Code quality and security analysis
   • Requires initial SonarQube project setup
   • Configure quality gates and thresholds
   • Use latest stable SonarQube version

3. Unit Tests (Strict)

   • Run full test suite
   • Generate coverage reports
   • Fail if tests fail or coverage drops below threshold

4. Linting (Strict)

   • Run Biome linting
   • Fail on linting errors
   • Optionally auto-fix and commit changes

Required GitHub Actions versions:

• actions/checkout@v4
• pnpm/action-setup@v2 (with pnpm version >= 10)
• actions/setup-node@v4 (with Node.js 22.x)

Example GitHub Actions workflow:

Note: The following PR checks are strict requirements - all must be included and pass before merging.

name: PR Checks

on:
  pull_request:
    branches: [main, develop]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm audit --audit-level=moderate

  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm run test:ci
      - uses: codecov/codecov-action@v3
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm run lint
      - run: pnpm run format:check

---

Docker

Containerization

Set up Docker and Docker Compose for local development and deployment.

Docker Compose Structure:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      - prometheus
      - grafana

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus
      - prometheus_data:/prometheus

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - prometheus

volumes:
  prometheus_data:
  grafana_data:

Dockerfile Best Practices:

• Use multi-stage builds for smaller images
• Leverage layer caching
• Use specific version tags for base images
• Run as non-root user when possible
• Include health checks

Additional Services:

• Database services (PostgreSQL, MySQL, MongoDB) can be added to docker-compose.yml as needed
• Configure service dependencies appropriately

---

GitHub CLI (gh) for DevOps

The GitHub CLI (gh) provides powerful commands for managing GitHub Actions workflows, runs, secrets, and other DevOps operations.

GitHub Actions Workflow Management

List and View Workflows:

# List all workflows in repository
gh workflow list

# View workflow details
gh workflow view <workflow-id>

# View workflow YAML file
gh workflow view <workflow-id> --yaml

# View workflow runs
gh run list

# View specific workflow run
gh run view <run-id>

# View workflow run logs
gh run view <run-id> --log

# Watch workflow run in real-time
gh run watch <run-id>

Run and Manage Workflows:

# Manually trigger a workflow
gh workflow run <workflow-id>

# Run workflow with inputs
gh workflow run <workflow-id> --field key=value

# Rerun a failed workflow
gh run rerun <run-id>

# Cancel a running workflow
gh run cancel <run-id>

# Delete workflow runs
gh run delete <run-id>

For AI Agents:

• Monitor CI/CD pipeline status after PR creation
• Automatically rerun failed workflows after fixes
• Cancel long-running workflows when needed
• Retrieve workflow logs for debugging

Cache Management

Manage GitHub Actions Caches:

# List all caches
gh cache list

# Delete specific cache
gh cache delete <cache-id>

# Delete all caches (use with caution)
gh cache list --json id --jq '.[].id' | xargs -I {} gh cache delete {}

For AI Agents:

• Clear corrupted caches that cause build failures
• Monitor cache usage and efficiency
• Clean up old caches to free space

Secrets and Variables Management

Repository Secrets:

# List secrets
gh secret list

# Set a secret
gh secret set SECRET_NAME --body "secret-value"

# Delete a secret
gh secret delete SECRET_NAME

Repository Variables:

# List variables
gh variable list

# Get variable value
gh variable get VARIABLE_NAME

# Set variable
gh variable set VARIABLE_NAME --body "variable-value"

# Delete variable
gh variable delete VARIABLE_NAME

For AI Agents:

• Securely manage secrets for CI/CD pipelines
• Configure environment-specific variables
• Rotate secrets when needed
• Verify secret configuration before workflow runs

Workflow Status Monitoring

Check PR Status:

# Check all checks for a PR
gh pr checks <pr-number>

# Wait for checks to complete
gh pr checks <pr-number> --watch

# View check details
gh run view <run-id> --log

For AI Agents:

• Wait for CI checks before merging PRs
• Report check status to users
• Retry failed checks automatically
• Block merges until all checks pass

Advanced Workflow Operations

Workflow Enable/Disable:

# Disable a workflow
gh workflow disable <workflow-id>

# Enable a workflow
gh workflow enable <workflow-id>

Download Artifacts:

# List artifacts from a run
gh run view <run-id> --json artifacts

# Download artifacts
gh run download <run-id>

For AI Agents:

• Temporarily disable workflows during maintenance
• Download build artifacts for testing
• Archive artifacts for deployment

Integration with CI/CD Pipeline

Example: Automated Deployment Workflow

#!/bin/bash
# Automated deployment script using gh CLI

# 1. Check if PR is ready
PR_NUMBER=$(gh pr list --head $(git branch --show-current) --json number -q '.[0].number')
if [ -z "$PR_NUMBER" ]; then
  echo "No PR found for current branch"
  exit 1
fi

# 2. Wait for all checks to pass
echo "Waiting for CI checks..."
gh pr checks $PR_NUMBER --watch

# 3. Verify checks passed
CHECKS_STATUS=$(gh pr checks $PR_NUMBER --json status -q '.[].status')
if [[ "$CHECKS_STATUS" == *"FAILURE"* ]]; then
  echo "Some checks failed. Deployment aborted."
  exit 1
fi

# 4. Merge PR
gh pr merge $PR_NUMBER --squash --delete-branch

# 5. Wait for deployment workflow
echo "Waiting for deployment workflow..."
DEPLOY_RUN=$(gh run list --workflow=deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')
gh run watch $DEPLOY_RUN

# 6. Verify deployment
DEPLOY_STATUS=$(gh run view $DEPLOY_RUN --json conclusion -q '.conclusion')
if [ "$DEPLOY_STATUS" != "success" ]; then
  echo "Deployment failed!"
  exit 1
fi

echo "Deployment successful!"

For AI Agents:

• Automate complete CI/CD pipeline from PR to deployment
• Monitor each stage and handle failures appropriately
• Provide status updates throughout the process
• Rollback on deployment failures

Environment and Deployment Management

Deployment Status:

# View deployment status (via API)
gh api repos/:owner/:repo/deployments

# View deployment environments
gh api repos/:owner/:repo/environments

For AI Agents:

• Track deployment status across environments
• Verify deployments before proceeding
• Manage environment-specific configurations

Best Practices for AI Agents

1. Always verify workflow status: Check gh pr checks before merging
2. Monitor long-running workflows: Use gh run watch for real-time updates
3. Handle failures gracefully: Implement retry logic for transient failures
4. Secure secret management: Never log or expose secret values
5. Use appropriate workflow triggers: Understand when to use manual vs automatic triggers
6. Clean up resources: Delete old caches and artifacts periodically
7. Provide clear status: Report workflow status in user-friendly format
8. Respect rate limits: Implement delays for bulk operations
9. Use JSON output: Parse --json output for programmatic processing
10. Error handling: Check exit codes and provide meaningful error messages

Troubleshooting CI/CD Issues

Common Commands for Debugging:

# View recent failed runs
gh run list --status failure --limit 10

# View logs for failed run
gh run view <run-id> --log --failed

# Check workflow syntax
gh workflow view <workflow-id> --yaml

# Verify secrets are set
gh secret list

# Check cache status
gh cache list

For AI Agents:

• Automatically diagnose CI/CD failures
• Suggest fixes based on error logs
• Verify configuration before retrying
• Report issues with actionable solutions

---

Additional Resources

• GitHub Actions Documentation
• Docker Documentation
• Docker Compose Documentation
• GitHub CLI Documentation
• GitHub Actions Workflow Syntax

---

Notes

• This document should be reviewed and updated regularly as best practices evolve
• Team-specific additions and modifications are encouraged
• When in doubt, refer to official documentation and community standards