# Atlas Agent Devops

> DevOps expertise for deployment, CI/CD, infrastructure, and automation Use when this capability is needed.

- Skill: `tomevault-io/atlas-agent-devops` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/atlas-agent-devops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/atlas-agent-devops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/atlas-agent-devops

---


# 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 | Purpose | URL | Database | Git State | Frequency |
|-------------|---------|-----|----------|-----------|-----------|
| Development | Local testing | localhost | Dev DB | Any | Multiple/day |
| Staging | Pre-production | staging.example.com | Stage DB | Clean | Before release |
| Production | Live users | example.com | Prod DB | Clean | Weekly |

**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:**
```bash
# .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:

```markdown
# 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
```bash
./scripts/deploy-staging.sh
```

### Production
```bash
./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:

```markdown
# 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**
```bash
# 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**

```bash
# 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)**
```bash
# 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.):
   ```markdown
   ## [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:

```bash
# 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:**
```bash
.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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ajstack22) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->