Skip to main content

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

The agentex-agents repository template ships with three Gitea Actions workflows that automate the build and deploy lifecycle for your agents. These workflows use the SGP Build and Deploy API to package your agent source code into container images and deploy them to SGP-managed Kubernetes clusters. Out of the box, merging to main triggers an automatic build and deploy. Pushes to feature branches trigger build-only validation. You can also trigger builds and deploys manually via workflow dispatch. You do not need to write these workflows from scratch. The template repository includes them pre-configured. Your responsibility is to understand when each workflow runs, how to configure your agent directories, and how to set up the required secrets.

​
How it works

When you push code that changes an agent, the CI/CD pipeline detects the change, builds a container image, and (on the main branch) deploys it. The following diagram shows the end-to-end flow for a merge to main: The pipeline auto-detects which agents changed by running git diff against the previous commit. Only agents with modified files are built, so a single push that touches multiple agents triggers parallel builds for each one.

​
The three workflows

The template repository includes three workflow files under .gitea/workflows/. Each serves a different purpose in the development lifecycle.
WorkflowTriggerBuilds?Deploys?Use case
cloud-build.yamlPush to non-main branches (agent paths)YesNoValidate builds on feature branches
cloud-build-and-deploy-on-push.yamlPush to main (agent paths) or manual dispatchYesYesBuild and deploy on merge to main
cloud-deploy.yamlManual dispatch or workflow callNoYesDeploy a specific image version or rollback

​
cloud-build.yaml: build on feature branches

This workflow triggers on pushes to any branch except main when files under teams/**/agents/** change. It auto-detects which agents were modified, packages the build context for each one, and submits a build request to the SGP Build API via POST /v5/builds. The workflow polls the build status until it succeeds or fails, with a 600-second timeout. This workflow does not deploy. Its purpose is to validate that your agent builds successfully before you merge.

​
cloud-build-and-deploy-on-push.yaml: build and deploy on main

This workflow triggers when files under teams/**/agents/** change on the main branch, or via manual dispatch. It builds container images for all changed agents and then deploys them. For each agent, the workflow:
  1. Packages the build context based on the agent’s manifest.yaml build configuration
  2. Submits the build to POST /v5/builds and polls until complete
  3. Reads the agent’s manifest.yaml and environments.yaml
  4. Submits a deployment to POST /v5/agentex/deployments with the resulting build_id
  5. Polls the deployment status until it reaches healthy or fails
The workflow uses a resolve_inputs.py helper script to derive the image name from the agent.name field in the manifest and to auto-select the environment from environments.yaml (auto-selected when only one environment is defined, which is the typical case).

​
cloud-deploy.yaml: standalone deploy

This workflow is manual-only. It deploys an existing image without rebuilding. You can trigger it via manual dispatch or call it from another workflow using workflow_call. Inputs include:
  • agent-path (required): path to the agent directory
  • agent-environment (required): environment key from environments.yaml
  • build-id OR image-name + image-tag: specify either a previous build ID or a direct image reference
The workflow submits POST /v5/agentex/deployments, polls until the deployment is healthy, and fetches deploy logs on failure.
Use the standalone deploy workflow for rollbacks. If a deployment fails, you can redeploy the previous known-good build by providing its build-id.

​
Workflow runs

After a workflow triggers, you can monitor its progress in the Gitea Actions UI. Each workflow run shows the individual steps, their status, and logs for each stage of the build and deploy process.
Gitea workflow run detail page showing build and deploy steps
The workflow run page displays:
  • Each step in the pipeline with pass/fail indicators
  • Timing information for build and deploy phases
  • Console output for debugging failed steps
If a build or deployment fails, expand the failed step to see the error output. Common failures include Dockerfile syntax errors, missing dependencies, and secret reference mismatches.

​
Manual dispatch

You can trigger a build and deploy for a specific agent without pushing code by using the manual dispatch form in Gitea Actions.
Gitea manual dispatch form with input fields for agent path and configuration
To trigger a manual dispatch:
  1. Navigate to the Actions tab in your Gitea repository
  2. Select the cloud-build-and-deploy-on-push.yaml workflow (or cloud-deploy.yaml for deploy-only)
  3. Click Run workflow
  4. Fill in the inputs:
    • agent-path (required): the path to your agent directory (for example, teams/my-team/agents/my-agent)
    • image-name (optional): overrides the image name derived from manifest.yaml. Should match the agent.name in your manifest.
    • agent-name (optional): overrides the agent name. Should match image-name (the resolve_inputs.py helper sets both to the same value by default).
    • image-tag (optional): overrides the auto-generated tag. Use a version number (e.g., v1.2.0) or a commit SHA. Defaults to the current commit SHA.
    • agent-environment (optional): must match an environment key in your environments.yaml. Auto-selected when only one environment is defined.
  5. Click Run workflow to start the pipeline
Manual dispatch is useful during initial setup, testing, or when you need to deploy a specific image tag. For routine development, merging to main triggers the build and deploy automatically.

​
Repository structure

The CI/CD workflows expect a specific directory layout. Each agent lives in its own directory under teams/<team>/agents/<agent-name>/ and contains the configuration files the workflows need. 
teams/
  my-team/
    agents/
      my-agent/
        manifest.yaml          # Build and agent configuration
        environments.yaml      # Deployment settings (namespace, resources, etc.)
        Dockerfile             # Container build instructions
        .dockerignore          # Files to exclude from build context
        src/
          main.py              # Agent source code
          requirements.txt     # Python dependencies
          ...
      another-agent/
        manifest.yaml
        environments.yaml
        Dockerfile
        src/
          ...
The workflows detect changes at the teams/**/agents/** path level. When you push a commit that modifies any file inside an agent directory, the corresponding workflow picks up that agent for building.

​
manifest.yaml

The manifest.yaml file defines your agent’s identity, build context, credentials, and deployment defaults. It is the primary configuration file the CI/CD workflows read when building and deploying your agent. 
kind: Agent

build:
  context:
    # Root directory for the build context, relative to the agent directory
    root: ../
    # Paths to include in the build context (relative to root)
    include_paths:
      - golden_agent
    # Path to the Dockerfile (relative to root)
    dockerfile: golden_agent/Dockerfile
    # Path to the .dockerignore file (relative to root)
    dockerignore: golden_agent/.dockerignore

agent:
  # Agent Communication Protocol type: "async" or "sync"
  acp_type: async
  # Unique agent name (used as the image name by default)
  name: golden-agent
  # Human-readable description shown in the SGP dashboard
  description: Generic Claude Agent SDK harness.
  # Temporal workflow configuration (for async agents)
  temporal:
    enabled: true
    workflows:
      - name: GoldenAgentWorkflow
        queue_name: golden_agent_queue
  # Secrets injected as environment variables at runtime
  credentials:
    - env_var_name: ANTHROPIC_API_KEY
      secret_name: anthropic-api-key
      secret_key: api-key

deployment:
  image:
    # Left empty; populated by the CI/CD pipeline
    repository: ""
    tag: "latest"
  imagePullSecrets:
    - name: agentex-acr-pull-secret
  global:
    replicaCount: 1
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"
      limits:
        cpu: "1000m"
        memory: "2Gi"

​
Key fields

build.context controls what files are sent to the cloud build service. Set root to the common ancestor directory, then use include_paths to specify which subdirectories to include. The dockerfile and dockerignore paths are relative to root. agent defines the agent’s identity and runtime configuration:
  • acp_type determines whether the agent uses synchronous request-response (sync) or asynchronous task-based (async) communication.
  • name is used as the default image name and must be unique within your account.
  • temporal configures Temporal workflow settings for async agents. Each workflow entry specifies the workflow class name and task queue.
  • credentials maps secrets stored in SGP to environment variables in the running container. Each entry references a secret by name and key, and injects it as the specified environment variable. See Secrets for how to create and manage these secrets.
deployment sets default resource requests and replica counts. These values can be overridden in environments.yaml.
The deployment.image.repository field is intentionally left empty. The CI/CD pipeline populates it automatically with the managed registry path during the build phase.

​
environments.yaml

The environments.yaml file defines deployment settings for your agent’s target environment: the Kubernetes namespace, authentication principal, resource limits, and Helm value overrides. The file has a top-level environments map with a named key for each environment. In practice, you define one environment per agent. The key name (e.g., dev.aws below) is arbitrary; the CI/CD pipeline’s resolve_inputs.py helper auto-selects it when only one environment is defined. 
schema_version: "v1"

environments:
  dev.aws:
    environment: dev
    kubernetes:
      namespace: "sgp-golden-agent"
    auth:
      principal:
        user_id: ac48a4a5-ca7f-4fcd-9724-f08dbc6b081f
        account_id: 69c69407ee5d19e1dce57d57
    helm_overrides:
      command:
        - uvicorn
        - project.acp:acp
        - --host
        - 0.0.0.0
        - --port
        - "8000"
      replicas: 1
      resources:
        requests:
          cpu: 500m
          memory: 1Gi
        limits:
          cpu: 1000m
          memory: 2Gi
      temporal-worker:
        enabled: true
        replicaCount: 1
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 1000m
            memory: 2Gi
      env:
        - name: SGP_ACCOUNT_ID
          value: "69c69407ee5d19e1dce57d57"
        - name: SGP_CLIENT_BASE_URL
          value: "http://egp-api-backend.egp.svc.cluster.local:80/public"

​
Key fields

kubernetes.namespace determines where the agent’s pods, services, and other resources are created. auth.principal provides the user_id and account_id used to authenticate API calls. These must correspond to a valid SGP service account with permissions to create deployments. helm_overrides lets you customize the container command, resource requests and limits, replica counts, Temporal worker configuration, and environment variables. Values specified here take precedence over the defaults in manifest.yaml. The env field uses array format ([{name: X, value: Y}]) for environment variables injected into the running container.

​
Required secrets

The CI/CD workflows authenticate with the SGP API using secrets stored in your Gitea repository’s Actions settings. You must configure the following secrets before the workflows can run.
SecretDescription
SGP_API_KEYAPI key for authenticating with the SGP Build and Deploy API
SGP_ACCOUNT_IDYour SGP account identifier
To add these secrets:
  1. Navigate to your Gitea repository settings
  2. Go to Actions > Secrets
  3. Add SGP_API_KEY with your SGP API key value
  4. Add SGP_ACCOUNT_ID with your account ID
The workflows use the in-cluster API base URL http://egp-api-backend.egp.svc.cluster.local/public by default. This is pre-configured in the workflow files and does not require a separate secret. If your cluster uses a different service address, update the SGP_BASE_URL variable in the workflow files directly.
These repository-level secrets are different from the agent-level secrets defined in manifest.yaml. Repository secrets authenticate the CI/CD pipeline itself, while agent secrets (in the credentials section of manifest.yaml) are injected into the running agent container at runtime.

​
Adding a new agent

To add a new agent to the CI/CD pipeline:
  1. Create the agent directory under your team’s path: 
    mkdir -p teams/my-team/agents/my-new-agent/src
  2. Add a manifest.yaml with your agent’s build context, name, and configuration. Use the example above as a starting point and update the agent.name, build.context paths, and credentials section for your agent.
  3. Add an environments.yaml with your deployment target configuration. Set the namespace, auth.principal, and any helm_overrides for your environment.
  4. Add a Dockerfile and .dockerignore at the paths referenced in your manifest.yaml. The Dockerfile should produce a container that runs your agent.
  5. Add your agent source code under src/ or wherever your Dockerfile expects it.
  6. Push to a feature branch to trigger cloud-build.yaml. Verify that the build completes successfully in the Gitea Actions UI.
  7. Merge to main to trigger cloud-build-and-deploy-on-push.yaml, which builds the agent and deploys it automatically using the configuration in environments.yaml.
  8. Verify the deployment in the SGP dashboard. Navigate to your agent’s detail page to confirm the deployment status is healthy.
Ensure your manifest.yaml references only secrets that have already been created in SGP. A deployment will fail if it references a secret that does not exist. See Secrets for setup instructions.

​
Next steps

  • API and SDK: access builds and deployments programmatically
  • sgpctl CLI: build, deploy, and inspect agents from the terminal
  • Secrets: create and rotate credentials referenced in manifest.yaml