Connect Codefresh to AI Agents: Manage Release Cycles and Images

You want to connect Codefresh to an AI agent so your system can autonomously manage release cycles, orchestrate GitOps deployments, debug failed builds, and handle manual approval gates. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Codefresh integration from scratch.

Giving a Large Language Model (LLM) read and write access to your CI/CD platform is a high-stakes engineering challenge. If your team uses ChatGPT, check out our guide on connecting Codefresh to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Codefresh to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools, map them to your agent framework, and safely execute infrastructure commands.

This guide breaks down exactly how to fetch AI-ready tools for Codefresh, bind them natively to an LLM using LangChain (or frameworks like LangGraph, CrewAI, or the Vercel AI SDK), and execute complex DevOps workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the Saas integration bottleneck.

The Engineering Reality of the Codefresh API

Giving an LLM access to external data sounds simple in a prototype. You write a fetch request, wrap it in an @tool decorator, and pass it to the model. In production against a complex CI/CD system, this approach collapses.

Codefresh is not a simple CRUD application. It is a dual-layered platform combining legacy pipeline execution with modern GitOps (Argo CD) environments. If you hardcode these interactions into your agent, you will spend your sprints writing defensive API code instead of improving your model's reasoning. Here are the specific quirks of the Codefresh API that will break naive agent implementations.

The Opaque Kubernetes Proxy Trap

Codefresh acts as a control plane for Kubernetes clusters. To facilitate this, the API provides proxy endpoints (e.g., /api/kubernetes/* and /api/clusters/*) that forward HTTP requests directly to the underlying cluster provider.

The problem? The upstream API specification does not - and cannot - enumerate the response fields for these endpoints. The response shape depends entirely on the cluster state and the exact sub-path invoked. Standard LLMs are trained to expect flat, predictable JSON schemas. When an agent calls a proxy endpoint and receives an untyped, deeply nested Kubernetes manifest, it often hallucinates field extractions or loses context. Your tool layer must wrap these opaque responses, extracting only the necessary status fields before returning them to the LLM's context window.

The Environments V2 Schism

Codefresh maintains two distinct concepts of "Environments." The classic runtime environments are managed via standard endpoints, but modern GitOps deployments (Argo CD applications) exist entirely within the "Environments V2" namespace.

If you expose the raw API to an agent, it will constantly confuse codefresh_environments_pause (classic) with codefresh_gitops_applications_bulk_update (Argo). An LLM cannot intuit which architecture your organization uses based on standard REST conventions. The integration layer must scope the available tools strictly to the environments your team actually operates, explicitly filtering out deprecated or parallel infrastructure concepts to reduce the model's attack surface.

Asynchronous Builds and Aggressive Rate Limiting

Triggering a pipeline in Codefresh does not return a completed build. It returns a bare JSON string containing a build ID. The agent must understand that it needs to pause and poll a separate status endpoint (get_single_codefresh_status_by_id) using that ID.

During this polling cycle, you will hit rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When Codefresh returns an HTTP 429, Truto passes that error directly back to the caller while normalizing the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). If your agent loop does not explicitly catch HTTP 429s, read these headers, and sleep the execution thread, your autonomous deployment will crash halfway through a production release.

Core Codefresh Tools for AI Agents

Instead of exposing hundreds of raw endpoints, Truto's /tools API provides highly scoped, proxy-based methods (built using LLM function calling). These methods enforce strict JSON schemas, validating the agent's input before it ever touches the Codefresh API.

Here are the critical tools for orchestrating Codefresh release cycles.

create_a_codefresh_pipelines_run

This tool allows the agent to trigger a specific pipeline execution. It accepts the pipeline name or ID and can pass runtime variables. It returns the newly created build ID, which the agent must use in subsequent calls to track progress.

"Trigger the frontend-production-deploy pipeline. Pass the target branch release-v2.4 as a runtime variable and return the execution ID."

list_all_codefresh_workflows

This tool retrieves the status of recent builds. It supports filtering by pipeline name, trigger, and date ranges. Agents use this to monitor the CI/CD environment and detect failed jobs without requiring manual webhooks.

"Check the status of all builds triggered in the last hour for the auth-service pipeline. If any failed, summarize the executed steps."

create_a_codefresh_gitops_application

For teams utilizing Argo CD via Codefresh Environments V2, this tool creates a new GitOps application. It requires a structured manifest payload defining the source repository, target cluster, and sync policies.

"Provision a new GitOps application named payment-gateway-staging. Point it to the staging branch of the payments-repo and target the us-east-1-cluster."

get_single_codefresh_image_by_id

This tool retrieves deep metadata about a specific container image managed by Codefresh, including its hash, branch, commit SHA, and assigned tags. Agents use this to verify the provenance of an image before promoting it.

"Fetch the metadata for image ID img-883a9c. Verify that it was built from the main branch and contains the security-scanned tag."

create_a_codefresh_approval_approve

When a Codefresh pipeline pauses for manual intervention, this tool allows an authorized agent to submit an approval. This is critical for building autonomous deployment chains that require multi-stage verification before hitting production.

"Approve the pending deployment gate for build ID 602be9cc2. Log the approval message as 'Verified by integration test agent.'"

list_all_codefresh_kubernetes_releases

This tool lists Helm releases deployed on a specific cluster managed by Codefresh. It returns the release name, chart version, namespace, and current status, allowing the agent to audit the actual state of the infrastructure.

"List all active Helm releases in the production namespace on the eu-central cluster. Identify any releases running a chart version older than 1.4.0."

To view the complete inventory of available tools, query parameters, and schema details, visit the Codefresh integration page.

Workflows in Action

By chaining these tools together, you can build agents that handle complex, multi-step release operations that typically require a human staring at a dashboard.

Scenario 1: Autonomous Build Triage and Remediation

DevOps teams lose hours manually investigating failed CI/CD pipelines. An agent can monitor the environment, detect failures, extract the context, and re-run the build in debug mode.

"Check our recent workflows. If the main backend pipeline failed in the last 30 minutes, find the build ID, extract the status, and immediately trigger a rebuild in debug mode so I can investigate the logs."

Execution flow:

1. The agent calls list_all_codefresh_workflows with a time filter to find the failed build.
2. It extracts the id from the failed workflow record.
3. It calls get_single_codefresh_build_by_id to retrieve the exact steps that failed.
4. It calls get_single_codefresh_builds_rebuild_debug_by_id passing the failed build ID, returning a new debug build ID to the user.

sequenceDiagram
    participant User as User
    participant Agent as AI Agent
    participant Codefresh as Codefresh API
    
    User->>Agent: "Check for failed builds and restart in debug mode."
    Agent->>Codefresh: list_all_codefresh_workflows (status=error)
    Codefresh-->>Agent: [ { "id": "bld-992a", "pipelineName": "backend-main" } ]
    Agent->>Codefresh: get_single_codefresh_build_by_id (id="bld-992a")
    Codefresh-->>Agent: { "status": "error", "steps": [...] }
    Agent->>Codefresh: get_single_codefresh_builds_rebuild_debug_by_id (id="bld-992a")
    Codefresh-->>Agent: "new-bld-883b"
    Agent-->>User: "Failed build bld-992a identified. Restarted in debug mode as new-bld-883b."

Scenario 2: GitOps Release Verification

When managing Argo CD applications via Codefresh Environments V2, an agent can verify that a newly built image has been properly registered and then provision the GitOps application to deploy it.

"Verify that the container image tagged 'v2.0-rc1' has passed security checks. If it has, create a new GitOps application to deploy it to the staging cluster."

Execution flow:

1. The agent calls get_single_codefresh_image_by_id to inspect the image metadata and verify tags.
2. Upon validating the security-scanned tag, it constructs the JSON manifest for Argo CD.
3. It calls create_a_codefresh_gitops_application with the manifest to deploy the infrastructure.
4. It uses list_all_codefresh_kubernetes_releases to confirm the cluster acknowledges the new deployment state.

Building Multi-Step Workflows

To build these workflows, you need a robust agent loop. When dealing with infrastructure APIs like Codefresh, the loop must handle execution state and respect API rate limits explicitly.

Truto normalizes upstream APIs into standardized tool definitions. Using Truto's SDKs (like truto-langchainjs-toolset), you fetch these tools dynamically based on the integrated account.

Here is how you initialize the tools and explicitly handle HTTP 429 rate limit responses within an agent execution loop.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage } from "@langchain/core/messages";
 
async function runCodefreshAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Fetch Codefresh tools dynamically via Truto
  const truto = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // Using the integrated account ID for the customer's Codefresh instance
  const tools = await truto.getTools("codefresh_account_id_9921");
 
  // 3. Bind the strict JSON schemas to the model
  const llmWithTools = llm.bindTools(tools);
 
  let messages = [
    new HumanMessage("Check the status of the 'auth-service' pipeline, and if it is waiting for approval, approve it.")
  ];
 
  // 4. The Agent Execution Loop
  while (true) {
    const response = await llmWithTools.invoke(messages);
    messages.push(response);
 
    if (!response.tool_calls || response.tool_calls.length === 0) {
      console.log("Agent finished:", response.content);
      break;
    }
 
    // Execute each requested tool
    for (const toolCall of response.tool_calls) {
      const selectedTool = tools.find((t) => t.name === toolCall.name);
      if (!selectedTool) continue;
 
      let success = false;
      let attempts = 0;
      const maxRetries = 3;
 
      while (!success && attempts < maxRetries) {
        try {
          attempts++;
          const toolResult = await selectedTool.invoke(toolCall.args);
          
          messages.push({
            role: "tool",
            tool_call_id: toolCall.id,
            name: toolCall.name,
            content: JSON.stringify(toolResult),
          });
          success = true;
 
        } catch (error: any) {
          // Explicit Rate Limit Handling
          // Truto passes 429s directly with standard headers. You MUST handle backoff.
          if (error.status === 429) {
            const resetHeader = error.headers['ratelimit-reset'];
            const waitSeconds = resetHeader ? parseInt(resetHeader, 10) : (2 ** attempts);
            
            console.warn(`Rate limited by Codefresh. Retrying in ${waitSeconds} seconds...`);
            await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
          } else {
            // For 4xx/5xx errors, return the error to the LLM so it can adjust arguments
            messages.push({
              role: "tool",
              tool_call_id: toolCall.id,
              name: toolCall.name,
              content: `Execution failed: ${error.message}`,
            });
            break; // Break retry loop, let LLM decide next steps
          }
        }
      }
    }
  }
}
 
runCodefreshAgent();

Why Architecture Matters for AI Agents

When an AI agent executes a tool, the success of that operation depends entirely on the underlying integration layer. If you build custom API wrappers for Codefresh, your engineering team assumes the burden of maintaining OAuth lifecycles, adapting to upstream schema drift, and writing extensive error-handling logic for Kubernetes proxies and legacy environments.

By utilizing Truto's /tools endpoint, you abstract away the API's idiosyncrasies. The LLM interfaces with stable, schema-validated proxy methods. Invalid arguments are rejected locally before network execution, reducing hallucination-driven errors. Rate limit headers are standardized, making retry logic predictable.

This architecture allows your team to focus on prompt engineering and workflow design, rather than writing boilerplate HTTP clients for CI/CD platforms.