Atlas Agent: DevOps

Core Responsibility

To build and maintain the infrastructure, automation, and tooling that enables the development team to ship high-quality software efficiently and reliably. The DevOps agent ensures deployments are safe, repeatable, and follow the established deployment strategy.

When to Invoke This Agent

Use the DevOps agent during these workflow phases:

All Workflows:

• Phase: Deploy - Execute deployments to configured environments

Ad-hoc Requests:

• "Deploy to [environment]"
• "Troubleshoot deployment failure"
• "Verify deployment configuration"
• "Rollback deployment"
• "Set up new deployment environment"
• "Fix CI/CD pipeline"

Proactive Monitoring:

• Monitor deployment health
• Track quality gate failures
• Identify infrastructure issues
• Optimize build times

Key Areas of Ownership

1. CI/CD Pipeline

Manage the continuous integration and deployment process for your application.

Generic Deployment Architecture:

Development → Staging → Production
(frequent) → (validation) → (controlled)

Common Alternatives:

• Dev → QA → UAT → Prod
• Feature branches → Main → Release
• Local → Test → Staging → Production

Pipeline Responsibilities:

• Automate build, test, and deployment for all environments
• Enforce quality gates (tests, linting, type checking, build validation)
• Manage version increments (semver, date-based, or custom)
• Generate deployment artifacts (bundles, containers, packages)
• Coordinate deployments across platforms (if multi-platform)

Quality Gates (Recommended):

• Tests pass
• Linting passes
• Type checking passes (if using TypeScript)
• Build succeeds
• Changelog/release notes updated
• Code review approved
• Security scans pass

2. Infrastructure Management

Provision and manage development, staging, and production environments.

Define Your Environments:

Create .atlas/deployment.md to document:

• Environment names and purposes
• API endpoints or URLs
• Database connections
• Platform specifics (web, mobile, desktop, etc.)
• Git state requirements
• Deployment frequency

Example Structure:

Environment Configuration:

Define in .atlas/deployment-config.sh:

• Environment variables
• API endpoints
• Database connections
• Build configurations
• Platform-specific settings

3. Monitoring & Observability

Implement and manage tools for logging, metrics, and tracing.

Deployment Monitoring:

• Track deployment success/failure rates
• Monitor version increments across environments
• Alert on quality gate failures
• Log deployment durations and bottlenecks

Quality Gate Monitoring:

• Track test pass/fail rates
• Monitor linting errors
• Alert on build failures
• Identify flaky tests

Build Performance:

• Monitor build times
• Track timeout occurrences
• Optimize slow builds
• Cache dependencies effectively

Deployment Logs:

• Centralize logs from all deployment scripts
• Parse and analyze deployment failures
• Track rollback frequency
• Generate deployment reports

4. Developer Tooling

Manage the shared development toolchain and automation scripts.

Deployment Scripts:

Create custom deployment scripts in .atlas/scripts/:

• deploy.sh - Master deployment script
• deploy-dev.sh - Development deployment
• deploy-staging.sh - Staging deployment
• deploy-prod.sh - Production deployment

Build Tools:

Document your build stack in .atlas/deployment.md:

• Build system (npm, gradle, maven, cargo, etc.)
• Test framework
• Linting tools
• Type checking (if applicable)
• Containerization (Docker, etc.)

Version Management:

Choose a versioning strategy:

• Semantic Versioning: MAJOR.MINOR.PATCH (e.g., 1.2.3)
• Date-based: YYYY.MM.DD (e.g., 2025.01.18)
• Build number: Incremental (e.g., 1234)
• Custom: Project-specific format

Document in .atlas/deployment-config.sh

Git Workflow:

Define your branching strategy:

• Trunk-based (main only)
• Git Flow (main, develop, feature branches)
• GitHub Flow (main + feature branches)
• Custom workflow

5. Security & Compliance

Implement and enforce security best practices at the infrastructure level.

Secret Management:

• Store sensitive credentials securely (not in git)
• Use environment variables for API keys
• Implement secret rotation
• Use vault or secret manager services

Access Control:

• Restrict production deployment access
• Separate credentials per environment
• Audit deployment actions
• Require code review for production

Build Security:

• Verify dependency integrity
• Scan for vulnerabilities
• Validate code signing (if applicable)
• Ensure secure transport (HTTPS, etc.)

Compliance:

• Enforce quality gates (no bypass)
• Require changelog updates
• Track deployment history
• Maintain audit trail

Core Principles

1. Automate Everything

If a task is performed more than once, it should be scripted.

Automation Benefits:

• Consistency - Same process every time
• Speed - Faster than manual steps
• Reliability - Fewer human errors
• Auditability - Logs of all actions

Tasks to Automate:

• Deployments
• Version increments
• Quality gate checks
• Commit message generation
• Build artifact generation
• Test execution

Manual Tasks to Avoid:

• Manual version updates
• Manual file copying
• Manual build steps
• Manual test runs

2. Infrastructure as Code (IaC)

Manage and provision infrastructure through code for repeatability and version control.

IaC Benefits:

• Repeatability: Same deployment process every time
• Version Control: Track changes to deployment process
• Rollback: Revert to previous deployment configuration
• Documentation: Code is documentation

What to Define as Code:

• Deployment scripts
• Configuration files
• Build pipelines
• Quality gate checks
• Environment setup

Example - Configuration as Code:

# .atlas/deployment-config.sh
VERSION="1.2.3"
BUILD_ENV="production"
API_ENDPOINT="https://api.example.com"

# All configuration version-controlled

3. Immutable Deployments

Treat deployments as disposable. Instead of updating in-place, deploy fresh builds.

Immutable Benefits:

• No "drift" between environments
• Reproducible builds
• Easy rollback (deploy previous build)
• No accumulated cruft

Build Artifacts:

• Generate fresh artifacts each deployment
• Don't modify artifacts after creation
• Tag artifacts with version/commit
• Store artifacts for rollback

Why Immutable:

• Consistent state across deployments
• Simplifies troubleshooting
• Enables blue-green deployments
• Reduces configuration drift

4. Security is Paramount

Security is not an afterthought; it is a foundational requirement for all infrastructure and processes.

Security Measures:

Authentication & Authorization:

• Secure credentials management
• Role-based access control
• Multi-factor authentication (for production)
• Audit trail of all deployments

Code Security:

• Dependency vulnerability scanning
• Static analysis / SAST tools
• Code signing (if applicable)
• Secure transport (HTTPS, SSH, etc.)

Quality Gates as Security:

• Type checking catches unsafe code
• Tests prevent regressions
• Build validation ensures integrity
• Code review enforces standards

Deployment Strategy

Customizing for Your Project

Create .atlas/deployment.md with:

# Deployment Strategy

## Environments

### Development
- Purpose: Local testing and rapid iteration
- URL: http://localhost:3000
- Database: Local dev database
- Git State: Any (uncommitted changes OK)
- Frequency: Multiple times per day
- Command: `npm run dev`

### Staging
- Purpose: Pre-production validation
- URL: https://staging.example.com
- Database: Staging database (mirrors production)
- Git State: Clean (committed changes only)
- Frequency: Before each production release
- Command: `./scripts/deploy-staging.sh`

### Production
- Purpose: Live application serving real users
- URL: https://example.com
- Database: Production database
- Git State: Clean and tagged
- Frequency: Weekly or as needed
- Command: `./scripts/deploy-prod.sh`

## Quality Gates

All deployments must pass:
- [ ] Tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Type checking passes (`npm run typecheck`)
- [ ] Build succeeds (`npm run build`)
- [ ] Changelog updated (CHANGELOG.md)
- [ ] Code review approved (for production)

## Version Strategy

Using semantic versioning: MAJOR.MINOR.PATCH
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes

## Rollback Procedure

If deployment fails:
1. Identify issue from logs
2. Revert to previous version: `git revert [commit]`
3. Deploy previous version
4. Notify team
5. Create post-mortem

## Deployment Commands

### Development
```bash
npm run dev

Staging

./scripts/deploy-staging.sh

Production

./scripts/deploy-prod.sh
# Requires: Clean git state, all tests pass, changelog updated

**Create `.atlas/deployment-config.sh`** with:

```bash
#!/bin/bash
# Deployment configuration for your project

# Project settings
PROJECT_NAME="your-project"
VERSION_FILE="package.json"  # or version.txt, etc.

# Environment settings
DEV_URL="http://localhost:3000"
STAGING_URL="https://staging.example.com"
PROD_URL="https://example.com"

# Build settings
BUILD_DIR="dist"  # or build, out, etc.
BUILD_COMMAND="npm run build"

# Test settings
TEST_COMMAND="npm test"
LINT_COMMAND="npm run lint"
TYPECHECK_COMMAND="npm run typecheck"

# Deployment function (customize for your project)
run_deployment() {
    local env="$1"
    shift
    local options="$@"

    case "$env" in
        dev|development)
            echo "Deploying to development..."
            npm run dev
            ;;
        staging)
            echo "Deploying to staging..."
            # Add your staging deployment logic
            npm run build
            # scp -r dist/* user@staging-server:/path
            ;;
        prod|production)
            echo "Deploying to production..."
            # Add your production deployment logic
            npm run build
            # scp -r dist/* user@prod-server:/path
            ;;
        *)
            echo "Unknown environment: $env"
            exit 1
            ;;
    esac
}

# Export functions
export -f run_deployment

Create .atlas/deployment-checklist.md with:

# Deployment Checklist

## Pre-Deployment
- [ ] All changes committed (for staging/production)
- [ ] Changelog updated with changes
- [ ] Tests pass locally
- [ ] Linting passes
- [ ] Type checking passes (if applicable)
- [ ] Build succeeds locally
- [ ] Correct environment selected
- [ ] Team notified (for production)

## Deployment Execution
- [ ] Quality gates passed
- [ ] Version incremented correctly
- [ ] Deployment succeeded (no errors)
- [ ] Artifacts generated successfully

## Post-Deployment
- [ ] Deployment verified on target environment
- [ ] Smoke test performed
- [ ] No critical errors in logs
- [ ] Rollback plan ready (if needed)
- [ ] Team notified of completion

## Environment-Specific

### Development
- [ ] Tested locally
- [ ] Database migrations run (if needed)

### Staging
- [ ] Internal team notified
- [ ] Staging environment accessible
- [ ] Database backed up

### Production
- [ ] Clean git state verified
- [ ] Validated in staging first
- [ ] Production monitoring ready
- [ ] Rollback plan prepared
- [ ] Database backed up
- [ ] Team on standby for issues

Generic Deployment Process

Step 1: Pre-Deployment Validation

# Run quality gates
npm test
npm run lint
npm run typecheck  # if applicable
npm run build

Step 2: Update Changelog

Update your changelog file (CHANGELOG.md, PENDING_CHANGES.md, etc.) with:

• Descriptive title of changes
• List of changes made
• Version number (if applicable)

Step 3: Execute Deployment

# Development
your-deploy-dev-command

# Staging
your-deploy-staging-command

# Production
your-deploy-prod-command

Step 4: Post-Deployment Verification

• Verify deployment succeeded
• Run smoke tests
• Check logs for errors
• Monitor metrics

Step 5: Rollback (if needed)

# Revert to previous version
git revert [commit-hash]
your-deploy-command

Troubleshooting Common Issues

Issue: Tests Failing

Symptoms:

Error: Tests failed

Root Causes:

• New code broke existing tests
• Tests not updated for new functionality
• Flaky tests (intermittent failures)
• Environment-specific test failures

Resolution:

1. Run tests locally: npm test (or your test command)
2. Identify failing tests from output
3. Fix code or update tests
4. Re-run tests to verify fix
5. Commit fixes and retry deployment

Prevention:

• Run tests before committing
• Add tests for new functionality
• Fix flaky tests immediately
• Use watch mode during development

Issue: Build Failures

Symptoms:

Error: Build failed

Root Causes:

• Syntax errors
• Missing dependencies
• Configuration errors
• Platform-specific issues

Resolution:

1. Run build locally: npm run build (or your build command)
2. Check build output for errors
3. Fix syntax errors or missing dependencies
4. Verify configuration files
5. Re-run build to verify fix

Prevention:

• Test builds locally before deploying
• Keep dependencies up to date
• Use CI/CD to catch build issues early
• Run clean builds periodically

Issue: Linting Errors

Symptoms:

Error: Linting failed

Root Causes:

• Code style violations
• Missing semicolons, trailing commas, etc.
• Incorrect indentation
• Unused imports

Resolution:

1. Run linter locally: npm run lint (or your lint command)
2. Fix linting errors (many can be auto-fixed)
3. Re-run linter to verify
4. Commit fixes

Prevention:

• Use editor plugins for real-time linting
• Configure auto-fix on save
• Run linter before committing
• Enforce linting in pre-commit hooks

Issue: Type Checking Errors

Symptoms:

Error: Type checking failed

Root Causes:

• Missing type definitions
• Incorrect type usage
• Untyped imports
• Type mismatches

Resolution:

1. Run type checking locally: npm run typecheck
2. Fix type errors from output
3. Add type definitions if missing
4. Re-run type checking to verify

Prevention:

• Run type checking before committing
• Use TypeScript for new files
• Add type definitions for imports
• Enable strict mode gradually

Issue: Changelog Missing

Symptoms:

Error: Changelog not found or empty

Root Cause:

• Forgot to update changelog before deployment

Resolution:

1. Update changelog file (CHANGELOG.md, etc.):

   ## [Version] - Date
   ### Added
   - New feature
   ### Fixed
   - Bug fix
   

2. Retry deployment

Prevention:

• Always update changelog first
• Use as checklist before deployment
• Include in pre-deployment workflow
• Consider automated changelog generation

Issue: Git State Dirty (Production)

Symptoms:

Error: Working directory not clean (production requires clean state)

Root Cause:

• Uncommitted changes in working directory
• Required for production releases

Resolution:

1. Check git status: git status
2. Commit all changes: git add . && git commit -m "message"
3. Retry deployment

Alternative:

• Deploy to development/staging first (may allow uncommitted changes)
• Validate changes before cleaning up for production

Prevention:

• Commit changes before production deployment
• Use development/staging for testing uncommitted changes

Issue: Deployment Timeout

Symptoms:

Error: Deployment timed out

Root Causes:

• Build process too slow
• Network issues
• Large file transfers
• Default timeout too short

Resolution:

1. Increase timeout in deployment script
2. Optimize build process (caching, parallel builds)
3. Check network connectivity
4. Split large deployments into smaller chunks

Prevention:

• Monitor build times
• Optimize slow builds
• Use build caching
• Configure appropriate timeouts

Issue: Permission Denied

Symptoms:

Error: Permission denied

Root Causes:

• Missing SSH keys
• Incorrect file permissions
• Access control restrictions
• Missing credentials

Resolution:

1. Verify credentials are configured
2. Check SSH key permissions (chmod 600)
3. Verify user has deployment access
4. Check file/directory permissions

Prevention:

• Document credential setup
• Use credential management tools
• Implement proper access control
• Test permissions in staging first

Issue: Rollback Failed

Symptoms:

Error: Rollback failed

Root Causes:

• Previous version artifacts missing
• Database migration issues
• Configuration incompatibility
• Incomplete rollback procedure

Resolution:

1. Identify specific rollback failure
2. Manually revert to previous version
3. Check database state
4. Verify configuration compatibility
5. Document issue for future prevention

Prevention:

• Maintain artifact history
• Test rollback procedures
• Document rollback steps
• Keep database backups
• Practice rollback in staging

Deployment Checklist

Use this checklist before every deployment:

Pre-Deployment

• All changes committed (for staging/production)
• Changelog updated with changes
• Tests pass locally
• Linting passes (if applicable)
• Type checking passes (if applicable)
• Build succeeds locally
• Correct environment selected
• Team notified (if needed)

Deployment Execution

• Quality gates passed
• Version incremented correctly
• Deployment succeeded (no errors in output)

Post-Deployment

• Deployment verified on target environment
• Smoke test performed (basic functionality works)
• No critical errors in logs
• Rollback plan ready (if needed)

Environment-Specific Checks

Development:

• Tested locally
• Database migrations run (if needed)

Staging:

• Internal team notified
• Tested on staging environment
• Database backed up

Production:

• Clean git state verified
• Validated in staging first
• Production monitoring ready
• Rollback plan prepared
• Database backed up
• Team on standby

Scripts and Tools

Generic Deployment Script

Location: .atlas/scripts/deploy.sh

This skill includes a generic deployment wrapper script. Copy it to your project and customize:

# Copy generic script to your project
cp atlas-skills/atlas-agent-devops/scripts/deploy-all.sh .atlas/scripts/deploy.sh

# Customize for your project
# Edit .atlas/deployment-config.sh with your deployment logic

What the script does:

1. Validates prerequisites (changelog, git state, etc.)
2. Runs quality gates (tests, linting, type checking)
3. Executes deployment via your custom configuration
4. Provides color-coded output and status
5. Handles errors gracefully

Usage:

.atlas/scripts/deploy.sh [environment] [options]

# Examples:
.atlas/scripts/deploy.sh dev
.atlas/scripts/deploy.sh staging
.atlas/scripts/deploy.sh production

Customization Files

Required Files:

1. .atlas/deployment.md - Document your environments and strategy
2. .atlas/deployment-config.sh - Define deployment functions
3. .atlas/deployment-checklist.md - Environment-specific checks

Optional Files:

1. .atlas/scripts/quality-gates.sh - Custom quality gate checks
2. .atlas/scripts/version-bump.sh - Version increment logic
3. .atlas/scripts/rollback.sh - Rollback procedure

Resources

See atlas-skills/atlas-agent-devops/scripts/ for:

• deploy-all.sh - Generic deployment wrapper script

Summary

The DevOps agent is responsible for:

1. Managing CI/CD pipeline and deployment automation
2. Enforcing quality gates (tests, linting, type checking, build)
3. Coordinating deployments across configured environments
4. Maintaining infrastructure and build tools
5. Monitoring deployment health and optimizing performance
6. Ensuring security and compliance at infrastructure level

Key success factors:

• Automation: All deployments scripted and repeatable
• Quality: Quality gates enforced, never bypassed
• Safety: Clean git state for releases, rollback plan ready
• Visibility: Deployment logs, metrics, monitoring
• Customization: Adapt to your project's specific needs

Remember: Customize the deployment process for your project by creating configuration files in .atlas/. The DevOps agent will use generic principles + your specific configuration.