Octopus Deploy Release Guru

An autonomous agent that manages Octopus Deploy release pipelines — creating releases, managing deployment processes, generating release notes, and orchestrating multi-environment deployments with approval gates.

When to Use This Agent

Choose Octopus Deploy Release Guru when:

• You need to create, manage, or troubleshoot Octopus Deploy releases
• You want automated release notes generation from commit history
• You need to orchestrate deployments across development, staging, and production
• Deployment pipelines need approval gates, variable management, or tenant configuration

Consider alternatives when:

• You are using a different CI/CD platform (GitHub Actions, Jenkins, GitLab CI)
• You need general DevOps guidance without Octopus Deploy specifics
• You are only building/testing code, not deploying it

Quick Start

Copy
# .claude/agents/octopus-deploy-guru.yml
name: octopus-deploy-release-guru
description: Manage Octopus Deploy releases and deployments
agent_prompt: |
  You are an Octopus Deploy Release expert. Help with:

  1. Creating releases with proper versioning and release notes
  2. Managing deployment processes across environments
  3. Configuring variables, lifecycles, and channels
  4. Implementing deployment patterns (blue-green, canary, rolling)
  5. Setting up tenant-based deployments for multi-customer SaaS
  6. Troubleshooting deployment failures and rollbacks

  Use the Octopus REST API for automation tasks.
  Follow semver for release versioning.

Example invocation:

Copy
claude "Create a release for project WebApp v2.5.0 with automated release notes from the last 20 commits and deploy to staging"

Sample release output:

Release Created — WebApp v2.5.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Release Notes (auto-generated):
  Features:
    - Add user dashboard analytics (#342)
    - Implement export to CSV (#338)
  Bug Fixes:
    - Fix login timeout on mobile (#351)
    - Resolve cart total rounding error (#349)
  Infrastructure:
    - Upgrade Node.js to 20.x (#345)

Deployment Status:
  ✓ Development → Deployed (auto)
  ⏳ Staging → Deploying...
  ⏸ Production → Awaiting staging approval

Variables Applied:
  Environment-specific: 12 variables resolved
  Sensitive: 3 secrets from key vault

Core Concepts

Release Pipeline Architecture

Stage	Environment	Trigger	Approval
Build	CI/CD	Git push	Automatic
Create Release	Octopus	Build success	Automatic
Deploy Dev	Development	Release created	Automatic
Deploy Staging	Staging	Dev success	Automatic
Deploy Production	Production	Staging success	Manual (2 approvers)

Octopus REST API Automation

Copy
# Create release via Octopus API
$OctopusUrl = "https://octopus.company.com"
$ApiKey = $env:OCTOPUS_API_KEY

# Create a release
$releaseBody = @{
    ProjectId = "Projects-123"
    Version = "2.5.0"
    ChannelId = "Channels-1"
    ReleaseNotes = $releaseNotes
    SelectedPackages = @(
        @{ ActionName = "Deploy WebApp"; Version = "2.5.0" }
    )
} | ConvertTo-Json

$release = Invoke-RestMethod `
    -Uri "$OctopusUrl/api/releases" `
    -Method Post `
    -Headers @{ "X-Octopus-ApiKey" = $ApiKey } `
    -Body $releaseBody `
    -ContentType "application/json"

# Deploy to environment
$deployBody = @{
    ReleaseId = $release.Id
    EnvironmentId = "Environments-2"  # Staging
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "$OctopusUrl/api/deployments" `
    -Method Post `
    -Headers @{ "X-Octopus-ApiKey" = $ApiKey } `
    -Body $deployBody `
    -ContentType "application/json"

Release Notes Generation

Copy
// Auto-generate release notes from git commits
function generateReleaseNotes(commits) {
  const categories = { features: [], fixes: [], infra: [], other: [] };

  for (const commit of commits) {
    const msg = commit.message;
    if (msg.startsWith('feat:') || msg.includes('#feat')) {
      categories.features.push(formatCommit(commit));
    } else if (msg.startsWith('fix:') || msg.includes('#fix')) {
      categories.fixes.push(formatCommit(commit));
    } else if (msg.startsWith('chore:') || msg.startsWith('infra:')) {
      categories.infra.push(formatCommit(commit));
    } else {
      categories.other.push(formatCommit(commit));
    }
  }

  let notes = '';
  if (categories.features.length) notes += `## Features\n${categories.features.join('\n')}\n\n`;
  if (categories.fixes.length) notes += `## Bug Fixes\n${categories.fixes.join('\n')}\n\n`;
  if (categories.infra.length) notes += `## Infrastructure\n${categories.infra.join('\n')}\n\n`;
  return notes;
}

Configuration

Option	Type	Default	Description
octopusUrl	string	required	Octopus Deploy server URL
apiKey	string	required	Octopus API key
projectName	string	required	Target project name
versionStrategy	string	"semver"	Versioning: semver, date-based, build-number
autoDeployTo	string[]	["Development"]	Environments for automatic deployment
releaseNotesSource	string	"git"	Source: git, jira, manual

Best Practices

1. Use channels for release stability tiers — Configure separate channels for alpha, beta, and stable releases. Alpha deploys automatically to dev, beta requires staging approval, and stable requires production sign-off. This prevents accidentally deploying a pre-release build to production.

2. Automate release notes from structured commit messages — Use conventional commits (feat:, fix:, chore:) and automatically categorize them into release notes. Manual release notes are consistently forgotten or incomplete. Automated notes ensure every change is documented.

3. Implement variable scoping carefully — Scope variables to the narrowest context needed. A database connection string should be scoped to a specific environment and tenant, not globally. Misconfigured variable scoping is the most common cause of "it works in staging but not production" deployments.

4. Set up deployment failure alerts with rollback instructions — When a deployment fails, the alert should include: which step failed, the error message, and a one-click rollback option. Fast rollback capability reduces the blast radius of failed deployments.

5. Test the deployment process itself, not just the code — Run deployment process tests in a disposable environment. Verify that variables resolve correctly, scripts execute, and health checks pass. A deployment process that has not been tested is a deployment process that will fail when you need it most.

Common Issues

Variable values differ between environments unexpectedly — A variable that should be environment-specific is set at the project level, causing all environments to use the same value. Audit variable scoping in Octopus: project-level variables apply everywhere unless overridden. Use the Octopus API to export all variables and verify scoping programmatically.

Deployment stuck in "executing" state — A deployment step hangs indefinitely, usually due to a script waiting for user input, a health check that never passes, or a tentacle connection timeout. Set step timeouts (e.g., 10 minutes maximum per step) and implement health check retries with a maximum attempt count. Check the Octopus server task log for the specific step that is stuck.

Release version conflicts with existing releases — Attempting to create a release with a version that already exists returns a conflict error. Implement version auto-increment logic that queries existing releases and increments the patch version. For hotfixes, use a branch-based version scheme like 2.5.0-hotfix.1.