Skip to main content

Overview

The agentex-agents repository template ships with 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. Each workflow file in the repository is a thin caller into the shared sgp/agentex-workflows repository, which holds the workflow logic and helper scripts. Out of the box, merging to main triggers an automatic build and deploy. Pull requests that change agent files trigger a build, and agents with an eval.yaml on main also get a preview deployment for the eval. 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 a pull request or a merge to main 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. When one push touches several agents, the workflow builds and deploys them one at a time in a single job, and a failure in one agent does not stop the others.

The workflows

The template repository includes these build and deploy workflow files under .gitea/workflows/. Each serves a different purpose in the development lifecycle.

cloud-build.yaml: build on pull requests

This workflow triggers on pull requests that change files under teams/**/agents/**. 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, one agent at a time. The workflow polls each build’s 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 select the environments.yaml entry for the current environment, as described in environments.yaml. Entries for other environments are skipped on merge and deploy through promotion. If more than one entry matches, not counting the one named by preview_environment, the run fails for that agent with an error asking for agent-environment.

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): key of an environments.yaml entry for the current environment
  • 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 in the current environment. If a deployment fails, you can redeploy the previous known-good build by providing its build-id. A rollback doesn’t change what promotion deploys next: the next promotion still deploys the commit recorded for the entry before it, not the rolled-back build.

pr-deploy-preview.yaml: preview a pull request

Comment /deploy-preview teams/my-team/agents/my-agent on a pull request to build that agent from the pull request’s head commit and deploy it as a preview deployment. The workflow runs only for commenters with write access, for pull requests from the same repository, and for agents that the pull request changes and that already exist on main, so a new agent can’t be previewed until it merges. The preview is labeled pr- followed by the pull request number and expires after 72 hours; add --ttl-hours with a value from 1 to 168 to change that. The result is posted as a comment on the pull request. Previews read manifest.yaml and environments.yaml from main and build the image from the pull request’s code, so configuration changes must merge before previews use them. cloud-preview-deploy.yaml runs the same build and preview deploy by manual dispatch, for a list of agent paths at a given commit.

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 whose entry targets the current environment. Defaults to the entry that matches CURRENT_ENVIRONMENT, as on merge.
  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.
The workflows detect changes at the teams/**/agents/** path level. When a pull request or a merge to main 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.

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.
Cloud deploys ignore deployment.image and deployment.imagePullSecrets. The server deploys the image recorded on the build and sets the pull secrets itself. The manifest schema still requires deployment.image.repository, so leave it as an empty string.

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. The key name (e.g., dev.aws below) is arbitrary. On merge to main, the CI/CD pipeline’s resolve_inputs.py helper deploys the entry whose environment field matches the repository’s CURRENT_ENVIRONMENT variable (dev when unset). An entry without an environment field counts as the current environment. Entries for other environments are promotion targets; see Promotion. A top-level preview_environment key names the entry that preview and eval deployments use, and that entry must be for the current environment.

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 customizes the agent’s pods. Values specified here take precedence over the defaults in manifest.yaml. The following keys are accepted, and a deploy request that sets any other key, such as the image or pull secrets, is rejected: replicas and temporal are also accepted so that older files keep deploying, but they have no effect. Use replicaCount and temporal-worker.

Promotion

Entries for environments other than the current one are promotion targets, and they don’t deploy on merge. A release admin runs each promotion from the sgp-release/agentex-promotion repository. Only release admins can see that repository and start runs there. To promote by hand, a release admin runs promote.yaml with these inputs:
  • target-environment: the environment to deploy into. The workflow refuses the current environment.
  • agents: the agents to promote.
  • commit-sha: the full 40-character commit SHA to deploy. The commit must be reachable from main.
If your platform team turns it on, scheduled-promote.yaml also runs in that repository. It reads the schedules in each agent’s environments.yaml and deploys each due entry with the commit last deployed to the entry listed before it. Every successful promotion records the commit as the git ref refs/deployed/<env>/<team>/<agent>. A cloud-deploy.yaml rollback doesn’t change what is promoted next.
Promotion entries follow these rules:
  • Entries are promoted in the order they are listed, so the first promotion entry needs an entry before it to promote from.
  • A promotion entry needs environment, auth.principal.account_id and a schedule.
  • schedule.cron must have 0 in its minute field, because schedules are checked once an hour. timezone is optional, defaults to UTC, and must be a whole number of hours from UTC.
  • Set schedule.enabled: false to pause an entry.
  • Entries for the current environment deploy on merge and can’t have a schedule.
  • Each target environment can have only one scheduled entry.
  • The settings for each target environment live on sgp-release/agentex-promotion, and release admins manage them. Don’t set them on your agent repository.

Required secrets and variables

The CI/CD workflows authenticate with the SGP API using your Gitea repository’s Actions settings. SGP_API_KEY is an Actions secret that you add yourself. The others are Actions variables. SGP sets them when it creates the repository, except where the table says otherwise, and it keeps any value you set. To configure them:
  1. Navigate to your Gitea repository settings
  2. Go to Actions > Secrets
  3. Add SGP_API_KEY with your SGP API key value
  4. Go to Actions > Variables and check that SGP_ACCOUNT_ID is set to your account ID. Add it if it is missing.
The workflows read the API base URL from the SGP_BASE_URL variable, except the preview deployments that /eval comments create, which always use the in-cluster address. If your cluster uses a different service address, change the variable; the workflow files don’t need edits.
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:
  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. Create the secrets that your manifest.yaml references. SGP rejects a deployment that references a secret that does not exist. See Secrets for setup instructions.
  7. Open a pull request to trigger cloud-build.yaml. Verify that the build completes successfully in the Gitea Actions UI.
  8. 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.
  9. Verify the deployment in the SGP dashboard. Navigate to your agent’s detail page to confirm the deployment status is healthy.

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