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 sharedsgp/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 tomain 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 underteams/**/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 underteams/**/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:
- Packages the build context based on the agent’s
manifest.yamlbuild configuration - Submits the build to
POST /v5/buildsand polls until complete - Reads the agent’s
manifest.yamlandenvironments.yaml - Submits a deployment to
POST /v5/agentex/deploymentswith the resultingbuild_id - Polls the deployment status until it reaches
healthyor fails
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 usingworkflow_call.
Inputs include:
agent-path(required): path to the agent directoryagent-environment(required): key of anenvironments.yamlentry for the current environmentbuild-idORimage-name+image-tag: specify either a previous build ID or a direct image reference
POST /v5/agentex/deployments, polls until the deployment is healthy, and fetches deploy logs on failure.
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.
- Each step in the pipeline with pass/fail indicators
- Timing information for build and deploy phases
- Console output for debugging failed steps
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.
- Navigate to the Actions tab in your Gitea repository
- Select the
cloud-build-and-deploy-on-push.yamlworkflow (orcloud-deploy.yamlfor deploy-only) - Click Run workflow
- 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 theagent.namein your manifest. - agent-name (optional): overrides the agent name. Should match
image-name(theresolve_inputs.pyhelper 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.yamlwhose entry targets the current environment. Defaults to the entry that matchesCURRENT_ENVIRONMENT, as on merge.
- agent-path (required): the path to your agent directory (for example,
- 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 underteams/<team>/agents/<agent-name>/ and contains the configuration files the workflows need.
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
Themanifest.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_typedetermines whether the agent uses synchronous request-response (sync) or asynchronous task-based (async) communication.nameis used as the default image name and must be unique within your account.temporalconfigures Temporal workflow settings for async agents. Each workflow entry specifies the workflow class name and task queue.credentialsmaps 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
Theenvironments.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 thesgp-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 frommain.
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.
- 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_idand aschedule. schedule.cronmust have0in its minute field, because schedules are checked once an hour.timezoneis optional, defaults to UTC, and must be a whole number of hours from UTC.- Set
schedule.enabled: falseto 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:
- Navigate to your Gitea repository settings
- Go to Actions > Secrets
- Add
SGP_API_KEYwith your SGP API key value - Go to Actions > Variables and check that
SGP_ACCOUNT_IDis 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.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:-
Create the agent directory under your team’s path:
-
Add a
manifest.yamlwith your agent’s build context, name, and configuration. Use the example above as a starting point and update theagent.name,build.contextpaths, andcredentialssection for your agent. -
Add an
environments.yamlwith your deployment target configuration. Set thenamespace,auth.principal, and anyhelm_overridesfor your environment. -
Add a
Dockerfileand.dockerignoreat the paths referenced in yourmanifest.yaml. The Dockerfile should produce a container that runs your agent. -
Add your agent source code under
src/or wherever your Dockerfile expects it. -
Create the secrets that your
manifest.yamlreferences. SGP rejects a deployment that references a secret that does not exist. See Secrets for setup instructions. -
Open a pull request to trigger
cloud-build.yaml. Verify that the build completes successfully in the Gitea Actions UI. -
Merge to main to trigger
cloud-build-and-deploy-on-push.yaml, which builds the agent and deploys it automatically using the configuration inenvironments.yaml. -
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