Documentation Index
Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Cloud Build and Deploy is the SGP-managed pipeline for packaging your Agentex agent code into a container image and deploying it to a Kubernetes cluster. You push your agent source code, SGP builds a container image in the cloud, and deploys it to a managed cluster where it becomes available for traffic.
This removes the need to manage Docker registries, Helm charts, or Kubernetes resources directly. SGP handles image building, artifact storage, Helm releases, health checks, and traffic routing. You interact with the system through the SGP dashboard UI, the sgpctl CLI, CI/CD pipelines (Gitea Actions), or the Build and Deploy REST API.
Cloud Build and Deploy supports both long-lived production deployments and ephemeral preview deployments for branch and PR testing. Builds and deployments are tracked with status history, event timelines, and container logs in the SGP dashboard.
The system is built around two configuration files in your agent repository: manifest.yaml (what to build and how to deploy) and environments.yaml (where to deploy). These files give you declarative control over the build and deploy lifecycle without writing infrastructure code.
How it works
The following diagram shows the end-to-end flow from pushing code to serving traffic:
The pipeline has two phases:
-
Build phase: Your CI pipeline (or a manual CLI/API call) sends the agent source code to the SGP Build Service via
POST /v5/builds. SGP builds a container image using the instructions in your manifest.yaml, including the base image, build arguments, and any referenced secrets. The resulting image is stored in a managed container registry. You do not need to configure or authenticate with the registry yourself.
-
Deploy phase: A deployment is created via
POST /v5/agentex/deployments. SGP generates a Helm release targeting the Kubernetes cluster and namespace specified in your environments.yaml. The deploy service monitors pod scheduling, image pulls, container startup, and health check responses. When all pods report healthy, SGP routes traffic to the new deployment and marks it as healthy.
By default, the CI/CD pipeline runs both phases automatically on merge to main. On feature branches, only the build phase runs. You can also trigger deployments manually from the UI, CLI, or API. You can redeploy a previous build without rebuilding.
A single build can have multiple deployment iterations (for example, if a deployment fails and you redeploy), but all deployments from a given build target the same environment.
Access methods
You can interact with Cloud Build and Deploy through four interfaces. Each supports the full build and deploy lifecycle.
| Interface | Best for | Details |
|---|
| SGP Dashboard UI | Visual monitoring, manual deployments, debugging | Point-and-click access to builds, deployments, logs, and events. No setup required beyond dashboard access. |
| CI/CD (Gitea Actions) | Automated builds and deploys, team workflows | Build on every push, build and deploy on merge to main. The recommended approach for production workflows. |
sgpctl CLI | Terminal workflows, scripting, debugging | Command-line tool for creating builds, deploying, inspecting status, and tailing logs. Useful for ad-hoc operations and shell scripts. |
| API and SDK | Programmatic access, custom integrations | REST API and Python/TypeScript SDKs for full control over builds and deployments. Use when you need to integrate with custom tooling or orchestration systems. |
Typical workflow
A typical development cycle looks like this:
-
Develop locally: Write and test your agent code on your local machine. Use the Agentex local development tools to verify behavior before pushing.
-
Push to a feature branch: The CI/CD pipeline triggers a build-only workflow to validate your agent compiles and packages correctly.
-
Merge to main: On merge, the CI/CD pipeline builds the agent and deploys it automatically using the configuration in
environments.yaml.
-
Monitor: The build and deployment appear on the agent detail page in the SGP dashboard. Build logs stream in real-time, and deployment events show rollout progress.
-
Verify: Check the deployment detail page for health status. For preview deployments (created separately via the UI or API/SDK), use the dedicated preview endpoint.
-
Iterate: If the deployment fails, use the events timeline and logs to diagnose the issue, fix the code, and push again.
Prerequisites
Before using Cloud Build and Deploy, ensure the following are in place:
- An Agentex agent repository: Your agent code must be in a Gitea repository accessible to SGP. See the Agentex agent types documentation if you have not yet created an agent.
- A
manifest.yaml file: Must exist at the root of your agent repository. Defines how SGP builds and deploys your agent.
- An
environments.yaml file: Defines the target environment (cluster, namespace, resource limits) for your deployments.
- Account-level secrets (if needed): If your agent requires API keys or other credentials, these must be created in the SGP secrets store before your first deployment. See Secrets.
- SGP API access: You need a valid SGP API key with permissions to create builds and deployments. This is configured in your CI/CD pipeline or CLI.
If you do not yet have an agent repository, follow the Agentex agent builder guide to scaffold a new agent project, then return here to set up the build and deploy pipeline. Key concepts
The following concepts are central to how Cloud Build and Deploy works.
Build
A build represents a single container image build from your agent’s source code. When you trigger a build, SGP packages the build context (your source files, manifest.yaml, and any referenced configuration), sends it to the build service, and produces a tagged container image. Each build is associated with a specific git commit and branch, providing full traceability from source to artifact.
Builds progress through the following statuses:
| Status | Description |
|---|
queued | Build request accepted, waiting for capacity |
running | Image build is in progress |
success | Image built and stored in the managed registry |
failed | Build failed due to an error in your code or Dockerfile |
cancelled | Build was cancelled by a user or automation |
timed_out | Build exceeded the maximum allowed duration |
error | An internal error occurred during the build |
Deployment
A deployment is a Helm release of a built container image to a Kubernetes cluster. Each deployment creates or updates the Kubernetes resources needed to run your agent: pods, services, ingress rules, and any associated config maps or secrets. The target namespace and resource configuration come from your environments.yaml.
Deployments progress through the following statuses:
| Status | Description |
|---|
pending | Deployment created, not yet started |
in_progress | Helm release is being applied to the cluster |
healthy | Pods are running and passing health checks |
failed | Deployment failed (pod crash, resource limits, misconfiguration) |
cancelled | Deployment was cancelled before completion |
Preview deployment
A preview deployment is an ephemeral deployment with an automatic TTL (time-to-live) teardown, designed for branch and PR testing. When you create a preview deployment, SGP provisions a dedicated endpoint where you can test the agent version built from your feature branch without affecting the production deployment.
Preview deployments are automatically cleaned up when:
- The configured TTL expires (default: 8 hours)
- You explicitly tear down the deployment
This makes preview deployments well-suited for code review workflows where reviewers need a live agent to test against. See Preview Deployments for configuration details.
Configuration files
Two YAML files in your agent repository control the build and deploy lifecycle:
manifest.yaml: defines your agent’s identity, build context, credentials, and deployment defaults. See the CI/CD guide for a full annotated reference.environments.yaml: defines the target environment (cluster, namespace, resource limits, Helm overrides). Read at deploy time, not build time, so you can change settings without rebuilding. See the CI/CD guide for details.
Your manifest.yaml can reference account-level Secrets that are injected as environment variables at runtime.
The SGP dashboard
The SGP dashboard provides a visual interface for monitoring builds and deployments. Key pages include:
- Agents page: lists all registered agents with their current deployment status. Access it from Agents in the left navigation.
- Agent detail page: shows build history, active deployment, and git metadata for a specific agent.
- Build detail page: shows all deployments created from a build, organized by type (production, preview, in-progress).
- Deployment detail page: provides the events timeline, container logs, status transitions, and configuration summary for a deployment.
See the UI walkthrough for step-by-step flows through these pages.
What’s next
This overview covers the core concepts and the UI surfaces for monitoring builds and deployments. The remaining guides in this section walk through specific workflows in detail:
| Guide | Description |
|---|
| UI walkthrough | Step-by-step flows for building and deploying from the SGP dashboard |
| CI/CD with Gitea Actions | Automated build and deploy pipelines triggered by git push |
| sgpctl CLI | Build, deploy, and inspect agents from the terminal |
| API and SDK | Programmatic access to builds and deployments via REST API and SDKs |
| Secrets | Store and reference credentials securely |
| Preview Deployments | Ephemeral branch deploys for PR testing |
manifest.yaml configuration and pipeline setup.
For terminal-based workflows, the sgpctl CLI guide covers installation, authentication, and common commands for building, deploying, and tailing logs.
