Bring your own AI to Octopus Deploy tasks

Background

Mid 2025 and Early 2026 saw the emergence of agentic CLI tools like Claude Code, GitHub Copilot CLI, Open AI Codex, and many more.

When compared to the previous waves of AI tooling, they were much more powerful & flexible. Don’t get me wrong - the previous generations were equally impressive for their time, but the CLI avatar in a way was how it was always meant to be. For record, the previous generations were:

1. IDE Extensions: These tools integrated directly into IDEs lead by GitHub Copilot. They were great for code generation and in-context assistance but passing relevant context was a challenge. You needed to open up the relevant files and hope the model could piece together the situation.
2. Chat Interfaces: Tools like ChatGPT and Claude’s web interface were fantastic for brainstorming and general queries but struggled with real-time context and integration into workflows. You had to copy-paste information back and forth, which was cumbersome.

To me, the CLIs offered a ways to orchestrate the AI either interactively or fully non-interactively. You could feed in context as arguments or files, and the model could return structured output that was easier to consume programmatically. This made them ideal for integrating into existing workflows and automation pipelines.

AI in pipelines

The CLI tools also began a newer trend closer to DevOps and Pipelines - Agentic Workflows - which supports the idea of dropping AI as a first-class actor within a pipeline that can observe, reason, and act based on the context it receives. Token economics permitting it has the potential to be a game changer for how we build and operate pipelines. From a pipeline authors perspective, AI Agents can help with:

• Iterating: Each pipeline needs to perform steps automatically, but the logic and structure of those steps can be iterated on much faster with an AI agent in the loop. Instead of manually changing the pipeline code, you can prompt the agent to suggest changes, test them, and implement them.
• Contextual Awareness: AI agents can consume a wide range of context about the pipeline run, the environment, and the deployment targets. This allows them to make informed decisions and take actions that are tailored to the specific situation, rather than relying on static logic.
• Troubleshooting: When a pipeline fails, an AI agent can analyze logs, inspect the state of the deployment targets, and suggest remediation steps. This can significantly reduce the time to resolution and help teams recover from incidents faster.
• Reasoning over data: AI agents can process and reason over large amounts of data, such as deployment logs, monitoring metrics, and configuration files. This allows them to identify patterns, detect anomalies, and make recommendations that would be difficult for a human to spot.

Bringing AI to Octopus Deploy

Octopus Deploy is a powerful deployment automation platform. To perform deployments, it has data of the target environment and enjoys first-party connectivity via Octopus Tentacles. This makes it an ideal candidate for use cases where you want to drop an AI agent into a system, run it with rich context, and have it report back its findings and actions as part of the process. It can technically perform actions but I think the sweet spot is to have it read, reason, and suggest next steps while a human makes the final call on what to execute.

This felt like a great project to get familiar with:

• Agentic CLI tools like Claude Code and GitHub Copilot CLI
• The Octopus API and step templates
• Model Context Protocol
• Prompt engineering for troubleshooting VMs and Kubernetes clusters

I built octopus-deploy-ai-steps as a concept. It’s a reusable step template that drops Claude Code or GitHub Copilot CLI into any Octopus runbook or deployment process as a non-interactive agent accepting Prompts as an input with a markdown report as the output. The reports are attached as artifacts to the deployment task, giving you a permanent record of what the agent suggested and why. The step template is designed to be flexible and extensible, so you can easily swap in different prompts, tools, or even AI models as needed.

How it works

The step template downloads the CLI tools and runs them with the prompts you provide. You use your API tokens to authenticate with the AI providers. It also supports MCP configuration so any relevant API tokens and endpoints can be passed in as parameters and the agent can call out to them during execution to enrich its context or take actions. The output is captured and published back to the Octopus task as an artifact. Post execution, it can be configured to clean up any installed dependencies or keep them around for faster subsequent runs.

Two entry points handle routing:

• scripts/octo-ai.sh — Linux and macOS workers
• scripts/octo-ai.ps1 — Windows workers

Three flags drive the behaviour:

Flag	Options
--ai-agent	claude or copilot
--os	linux or windows
--mode	container or local

The agent receives your prompt along with Octopus API credentials and can query the Octopus REST API directly to inspect the deployment, space, environment, or release context.

Architecture

The entry point scripts do only one thing — read the routing flags and delegate. Everything else is handled by the platform-specific agent scripts that source shared library code and run a nine-step execution flow.

flowchart TD
    Caller["Caller<br/>(Octopus step / shell)<br/>--ai-agent --os --mode --install-dependencies<br/>--ai-agent-api-key --octopus-api-key<br/>--octopus-server-url --octopus-space-name<br/>--prompt-content --mcp-configuration<br/>--allowed-tools --max-turns --gh-pat"]

    Entry["octo-ai.sh / octo-ai.ps1<br/><em>entry point</em><br/>reads only routing flags<br/>passes ALL args verbatim"]

    InstallDeps["install-dependencies.sh / .ps1"]

    AgentScripts["claude-linux.sh · claude-windows.ps1<br/>copilot-linux.sh · copilot-windows.ps1<br/><em>sources lib/common.* — nine-step execution flow</em>"]

    ResolvePrompt["resolve_prompt<br/>(fetch or read)"]
    WriteMCP["write_mcp_config<br/>(substitutes placeholders,<br/>writes workdir/mcp-config.json)"]
    InstallNode["install_node + install_npm_tool<br/>(local mode only)"]

    AICLI["AI CLI process<br/>claude -p - ...  /  copilot --prompt ..."]

    Output["stdout → workdir/output.json<br/>stderr → workdir/agent-stderr.log"]

    Artifacts["publish_all_artifacts<br/>POST /api/spaces/all → resolve space ID<br/>POST /api/{spaceId}/artifacts → create record<br/>PUT /api/{spaceId}/artifacts/{id}/content → upload"]

    Log["INFO: Uploaded artifact: name (Artifacts-...)"]

    Cleanup["cleanup_workdir<br/>(if --cleanup=true)"]

    Caller --> Entry
    Entry -->|"--mode=local --install-dependencies=true"| InstallDeps
    InstallDeps --> AgentScripts
    Entry --> AgentScripts
    AgentScripts --> ResolvePrompt & WriteMCP & InstallNode
    ResolvePrompt & WriteMCP & InstallNode --> AICLI
    AICLI --> Output
    Output --> Artifacts
    Artifacts --> Log
    Log --> Cleanup

Setting it up

Prerequisites

• Octopus Deploy 2024.1 or later
• An Anthropic API key (for Claude) or a GitHub token with Copilot scope

Step template configuration

When registering the step template in Octopus, set the script source to the Git repository:

• Repository URL: https://github.com/rohitnb/octopus-deploy-ai-steps
• Branch: main
• Script: scripts/octo-ai.sh (Linux) or scripts/octo-ai.ps1 (Windows)

Parameters

The template exposes required and optional parameters:

Required:

• AI agent selection (claude or copilot)
• Worker operating system
• Execution mode (container or local)
• API credentials (Anthropic key or GitHub token)
• Octopus API key and server URL
• Target space name
• Prompt content — inline text, a local file path, or a GitHub URL

Optional:

• Dependency auto-install flag (for local mode)
• MCP server configuration
• Tool allowlist for restricting agent capabilities
• Cleanup behaviour

Storing secrets

Use a centralized Octopus variable set to share configuration across projects. Mark API keys and tokens as sensitive so Octopus masks them in logs.

Execution modes

Container mode (recommended for Linux workers with Docker) runs the agent inside a pre-built image from the GitHub Container Registry. Consistent, reproducible, no dependency management on the worker.

Local mode runs the scripts directly on the deployment target. Useful when Docker isn’t available. Set --install-dependencies=true on the first run to have the script install Node.js and the CLI tools automatically.

Advanced features

MCP servers — extend agent capabilities by wiring in Model Context Protocol servers. Useful for giving the agent access to internal tools, APIs, or knowledge bases beyond what the Octopus API provides.

Tool allowlists — restrict which tools the agent can call. Useful when you want the agent to read and reason but not take write actions.

Artifact management — agent output can be linked back to the Octopus deployment task as an artifact, giving you a permanent record of what the agent said and why.

---

The project is open source. If you’re already running Octopus and want to experiment with agentic steps, the repository has the scripts and the configuration guide walks through the full setup.