Back to Details

gitops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
<objective>
路由说明：如果用户意图不明确，请使用references/intent-clarification.md中的通用澄清模板。
<objective>

GitOps with TrueFoundry

基于TrueFoundry的GitOps

Set up GitOps-style deployments with TrueFoundry. Store deployment configurations as YAML specs in Git and auto-deploy on push using 
tfy apply
in CI/CD pipelines.
使用TrueFoundry搭建GitOps模式的部署流程。将部署配置以YAML规范的形式存储在Git中，在CI/CD流水线中通过
tfy apply
实现代码推送后自动部署。

When to Use

适用场景

Set up automated Git-based deployments with 
tfy apply
. Store TrueFoundry YAML specs in Git and auto-deploy on push/merge via CI/CD pipelines.
需要使用
tfy apply
搭建基于Git的自动化部署流程，将TrueFoundry YAML规范存储在Git中，通过CI/CD流水线在代码推送/合并后自动部署。

When NOT to Use

不适用场景

  • User wants to deploy manually from local code → prefer 
    deploy
    skill; ask if the user wants another valid path
  • User wants to deploy an LLM model → prefer 
    llm-deploy
    skill; ask if the user wants another valid path
  • User wants to check what's deployed → prefer 
    applications
    skill; ask if the user wants another valid path
  • User wants to deploy a Helm chart → prefer 
    helm
    skill; ask if the user wants another valid path
  • User just wants to check TrueFoundry connection → prefer 
    status
    skill; ask if the user wants another valid path
</objective> <context>
  • 用户想要从本地代码手动部署 → 优先使用
    deploy
    技能；询问用户是否需要选择其他有效路径
  • 用户想要部署LLM模型 → 优先使用
    llm-deploy
    技能；询问用户是否需要选择其他有效路径
  • 用户想要查看已部署的内容 → 优先使用
    applications
    技能；询问用户是否需要选择其他有效路径
  • 用户想要部署Helm chart → 优先使用
    helm
    技能；询问用户是否需要选择其他有效路径
  • 用户仅想要检查TrueFoundry连接状态 → 优先使用
    status
    技能；询问用户是否需要选择其他有效路径
</objective> <context>

Prerequisites

前置条件

Always verify before setting up GitOps:
  1. Credentials — 
    TFY_BASE_URL
    and 
    TFY_API_KEY
    must be set (env or 
    .env
    )
  2. TrueFoundry CLI — 
    tfy
    CLI must be available in the CI/CD environment (installed via 
    pip install truefoundry
    )
  3. Git repository — A Git repo to store deployment specs
For credential check commands and .env setup, see 
references/prerequisites.md
. Use the 
status
skill to verify connection before proceeding.
</context> <instructions>
搭建GitOps前请务必确认以下内容：
  1. 凭证 — 
    TFY_BASE_URL
    和
    TFY_API_KEY
    必须配置完成（环境变量或
    .env
    文件中）
  2. TrueFoundry CLI — CI/CD环境中必须安装
    tfy
    CLI（可通过
    pip install truefoundry
    安装）
  3. Git仓库 — 用于存储部署规范的Git仓库
如需凭证检查命令和.env配置说明，请查看
references/prerequisites.md
。在继续操作前请使用
status
技能验证连接状态。
</context> <instructions>

How GitOps Works with TrueFoundry

TrueFoundry的GitOps工作原理

GitOps treats Git as the single source of truth for deployment configurations. The workflow is:
  1. Store specs in Git — All TrueFoundry resource YAML specs live in the repository
  2. Review via pull requests — Changes are reviewed before merging, with 
    tfy apply --dry-run
    validating specs in CI
  3. Auto-deploy on merge — When specs are merged to the default branch, 
    tfy apply
    deploys them automatically
  4. Full audit trail — Git history tracks every change, who made it, and when
GitOps将Git作为部署配置的唯一可信源，工作流程如下：
  1. 将规范存储在Git中 — 所有TrueFoundry资源的YAML规范都存放在代码仓库中
  2. 通过拉取请求进行评审 — 变更在合并前需经过评审，CI中通过
    tfy apply --dry-run
    验证规范的有效性
  3. 合并后自动部署 — 当规范被合并到默认分支时，
    tfy apply
    会自动完成部署
  4. 完整审计追踪 — Git历史记录会追踪每一次变更、变更提交人及提交时间

Repository Organization

仓库组织方式

Organize your repo with directories for each resource type:
truefoundry-configs/
├── clusters/
│   └── my-cluster/
│       ├── dev-workspace/
│       │   ├── my-api-service.yaml
│       │   ├── my-worker.yaml
│       │   └── my-llm.yaml
│       ├── staging-workspace/
│       │   ├── my-api-service.yaml
│       │   └── my-worker.yaml
│       └── prod-workspace/
│           ├── my-api-service.yaml
│           └── my-worker.yaml
├── gateway/
│   ├── models.yaml
│   ├── guardrails.yaml
│   └── tool-servers.yaml
├── integrations/
│   └── custom-integration.yaml
├── teams/
│   └── my-team.yaml
└── virtualaccounts/
    └── my-account.yaml
按资源类型创建目录来组织仓库内容：
truefoundry-configs/
├── clusters/
│   └── my-cluster/
│       ├── dev-workspace/
│       │   ├── my-api-service.yaml
│       │   ├── my-worker.yaml
│       │   └── my-llm.yaml
│       ├── staging-workspace/
│       │   ├── my-api-service.yaml
│       │   └── my-worker.yaml
│       └── prod-workspace/
│           ├── my-api-service.yaml
│           └── my-worker.yaml
├── gateway/
│   ├── models.yaml
│   ├── guardrails.yaml
│   └── tool-servers.yaml
├── integrations/
│   └── custom-integration.yaml
├── teams/
│   └── my-team.yaml
└── virtualaccounts/
    └── my-account.yaml

Key Principles

核心原则

  • One YAML file per resource — Each TrueFoundry resource (service, job, model, etc.) gets its own file
  • Filename matches resource name — The YAML filename should match the 
    name
    field inside the spec
  • Separate directories per workspace — Keep dev, staging, and prod configs in separate directories
  • Extract specs from the UI — Use "Edit -> Apply Using YAML" in the TrueFoundry dashboard to get the YAML spec for any existing resource
  • 每个资源对应一个YAML文件 — 每个TrueFoundry资源（服务、任务、模型等）都有独立的配置文件
  • 文件名与资源名一致 — YAML文件名需与规范内部的
    name
    字段值匹配
  • 各工作空间目录独立 — 将开发、预发、生产环境的配置存放在独立目录中
  • 从UI导出规范 — 使用TrueFoundry控制台中的「编辑 -> 使用YAML应用」功能，获取任意现有资源的YAML规范

Manifest File Structure

清单文件结构

Each YAML spec follows the standard TrueFoundry manifest format. For example, a service spec:
yaml
type: service
name: my-api-service
image:
  type: image
  image_uri: my-registry/my-app:latest
  command: uvicorn main:app --host 0.0.0.0 --port 8000
ports:
  - port: 8000
    expose: true
    protocol: TCP
    app_protocol: http
    host: my-api-dev.ml.example.truefoundry.cloud
workspace_fqn: my-cluster:dev-workspace
env:
  APP_ENV: development
  LOG_LEVEL: debug
replicas:
  min: 1
  max: 3
resources:
  cpu_request: 0.5
  cpu_limit: 1.0
  memory_request: 512
  memory_limit: 1024
每个YAML规范都遵循标准的TrueFoundry清单格式，例如服务规范：
yaml
type: service
name: my-api-service
image:
  type: image
  image_uri: my-registry/my-app:latest
  command: uvicorn main:app --host 0.0.0.0 --port 8000
ports:
  - port: 8000
    expose: true
    protocol: TCP
    app_protocol: http
    host: my-api-dev.ml.example.truefoundry.cloud
workspace_fqn: my-cluster:dev-workspace
env:
  APP_ENV: development
  LOG_LEVEL: debug
replicas:
  min: 1
  max: 3
resources:
  cpu_request: 0.5
  cpu_limit: 1.0
  memory_request: 512
  memory_limit: 1024

Environment-Specific Configs (Dev / Staging / Prod)

环境专属配置（开发/预发/生产）

Maintain separate YAML files per environment. Common differences:
SettingDevStagingProd
replicas.min
112+
replicas.max
1310+
resources.cpu_request
0.250.51.0+
resources.memory_request
2565121024+
env.LOG_LEVEL
debuginfowarn
ports.host
*-dev.*
*-staging.*
*-prod.*
workspace_fqn
cluster:dev-ws
cluster:staging-ws
cluster:prod-ws
Example directory layout:
clusters/my-cluster/
├── dev-workspace/
│   └── my-service.yaml       # min resources, 1 replica, debug logging
├── staging-workspace/
│   └── my-service.yaml       # moderate resources, autoscaling, info logging
└── prod-workspace/
    └── my-service.yaml        # full resources, HA replicas, warn logging
为每个环境维护独立的YAML文件，常见差异如下：
配置项开发环境预发环境生产环境
replicas.min
112+
replicas.max
1310+
resources.cpu_request
0.250.51.0+
resources.memory_request
2565121024+
env.LOG_LEVEL
debuginfowarn
ports.host
*-dev.*
*-staging.*
*-prod.*
workspace_fqn
cluster:dev-ws
cluster:staging-ws
cluster:prod-ws
示例目录结构：
clusters/my-cluster/
├── dev-workspace/
│   └── my-service.yaml       # 最低资源配置、1个副本、debug级别日志
├── staging-workspace/
│   └── my-service.yaml       # 中等资源配置、自动扩缩容、info级别日志
└── prod-workspace/
    └── my-service.yaml        # 全量资源配置、高可用副本、warn级别日志

Using 
tfy apply
in CI/CD Pipelines

在CI/CD流水线中使用
tfy apply

The 
tfy apply
command is the core of GitOps with TrueFoundry.
tfy apply
命令是TrueFoundry GitOps的核心。

Basic Usage

基础用法

bash
undefined
bash
undefined

Install TrueFoundry CLI (pin version range to prevent supply-chain attacks)

安装TrueFoundry CLI（固定版本范围避免供应链攻击）

pip install 'truefoundry>=0.5.0,<1.0'
pip install 'truefoundry>=0.5.0,<1.0'

Authenticate (uses TFY_HOST and TFY_API_KEY env vars)

认证（使用TFY_HOST和TFY_API_KEY环境变量）

TFY_HOST is the TrueFoundry platform URL (same as TFY_BASE_URL)

TFY_HOST是TrueFoundry平台URL（与TFY_BASE_URL一致）

Dry run — validate without deploying

试运行 — 仅验证不部署

tfy apply --file path/to/spec.yaml --dry-run
tfy apply --file path/to/spec.yaml --dry-run

Apply — deploy the spec

应用 — 部署规范

tfy apply --file path/to/spec.yaml
undefined
tfy apply --file path/to/spec.yaml
undefined

Applying Multiple Files

批量应用文件

To apply all changed files in a CI/CD pipeline, detect which files were modified in the commit or PR:
bash
undefined
要在CI/CD流水线中应用所有变更的文件，可检测提交或PR中修改的文件：
bash
undefined

Apply each changed YAML file

应用每个变更的YAML文件

while IFS= read -r file; do [ -z "$file" ] && continue echo "Applying $file..." tfy apply --file "$file" done < <(git diff --name-only HEAD~1 HEAD -- '*.yaml')
undefined
while IFS= read -r file; do [ -z "$file" ] && continue echo "Applying $file..." tfy apply --file "$file" done < <(git diff --name-only HEAD~1 HEAD -- '*.yaml')
undefined

Handling Deleted Files

处理已删除文件

When a YAML spec file is deleted from the repo, the corresponding resource should be removed. The CI/CD pipeline should detect deleted files and handle them:
bash
undefined
当YAML规范文件从仓库中删除时，对应的资源也需要被移除。CI/CD流水线需要检测删除的文件并进行处理：
bash
undefined

Warn about deleted files

对删除的文件发出警告

while IFS= read -r file; do [ -z "$file" ] && continue echo "WARNING: $file was deleted. Remove the resource manually from the TrueFoundry dashboard." done < <(git diff --name-only --diff-filter=D HEAD~1 HEAD -- '*.yaml')
undefined
while IFS= read -r file; do [ -z "$file" ] && continue echo "WARNING: $file was deleted. Remove the resource manually from the TrueFoundry dashboard." done < <(git diff --name-only --diff-filter=D HEAD~1 HEAD -- '*.yaml')
undefined

CI/CD Integration

CI/CD集成

For complete workflow files for each CI provider:
  • GitHub Actions: See references/gitops-github-actions.md -- PR validation (dry-run) and merge-to-deploy workflows, plus required secrets setup.
  • GitLab CI: See references/gitops-gitlab-ci.md -- validate and deploy stages with caching.
  • Bitbucket Pipelines: See references/gitops-bitbucket-pipelines.md -- PR validation and branch-based deploy.
All providers require 
TFY_HOST
and 
TFY_API_KEY
as repository secrets/variables.
如需各CI提供商的完整工作流文件，请查看：
  • GitHub Actions：查看references/gitops-github-actions.md — 包含PR验证（dry-run）和合并部署工作流，以及所需的密钥配置说明。
  • GitLab CI：查看references/gitops-gitlab-ci.md — 包含带缓存的验证和部署阶段配置。
  • Bitbucket Pipelines：查看references/gitops-bitbucket-pipelines.md — 包含PR验证和基于分支的部署配置。
所有提供商都需要将
TFY_HOST
和
TFY_API_KEY
配置为仓库密钥/变量。

Step-by-Step: Setting Up GitOps (Summary)

GitOps搭建步骤（概览）

  1. Verify TrueFoundry connection — Use the 
    status
    skill to confirm credentials
  2. Create the repo structure — Set up directories for your resource types (clusters, gateway, etc.)
  3. Export existing specs — In the TrueFoundry dashboard, go to each resource -> Edit -> Apply Using YAML. Save each spec as a YAML file in the repo.
  4. Add CI/CD workflows — Copy the appropriate workflow files for your CI provider (see above)
  5. Set repository secrets — Add 
    TFY_HOST
    and 
    TFY_API_KEY
    as secrets/variables in your CI provider
  6. Test with a dry run — Open a PR with a small change to verify the validation pipeline works
  7. Merge and deploy — Merge the PR and confirm the apply pipeline deploys successfully
</instructions>
<success_criteria>
  1. 验证TrueFoundry连接 — 使用
    status
    技能确认凭证有效
  2. 创建仓库结构 — 为不同资源类型（集群、网关等）创建对应目录
  3. 导出现有规范 — 在TrueFoundry控制台中，进入每个资源 -> 编辑 -> 使用YAML应用，将每个规范保存为仓库中的YAML文件。
  4. 添加CI/CD工作流 — 复制适用于你的CI提供商的工作流文件（见上文）
  5. 配置仓库密钥 — 在你的CI提供商中将
    TFY_HOST
    和
    TFY_API_KEY
    添加为密钥/变量
  6. 试运行测试 — 提交包含小改动的PR，验证验证流水线是否正常工作
  7. 合并部署 — 合并PR，确认应用流水线成功完成部署
</instructions>
<success_criteria>

Success Criteria

成功标准

  • The user has a Git repository with TrueFoundry YAML specs organized by environment (dev/staging/prod)
  • The CI/CD pipeline validates specs on pull requests using 
    tfy apply --dry-run
  • The CI/CD pipeline auto-deploys specs on merge to the default branch using 
    tfy apply
  • The agent has provided the user with the correct CI workflow files for their CI provider (GitHub Actions, GitLab CI, or Bitbucket Pipelines)
  • Repository secrets (
    TFY_HOST
    , 
    TFY_API_KEY
    ) are configured in the CI provider
  • The user can verify the pipeline works by opening a PR with a small YAML change and seeing validation pass
</success_criteria>
<references>
  • 用户拥有按环境（开发/预发/生产）组织的存储TrueFoundry YAML规范的Git仓库
  • CI/CD流水线在拉取请求阶段使用
    tfy apply --dry-run
    验证规范有效性
  • CI/CD流水线在合并到默认分支时使用
    tfy apply
    自动部署规范
  • Agent已为用户提供适配其CI提供商（GitHub Actions、GitLab CI或Bitbucket Pipelines）的正确CI工作流文件
  • 仓库密钥（
    TFY_HOST
    、
    TFY_API_KEY
    ）已在CI提供商中完成配置
  • 用户可以通过提交包含小改动的YAML文件的PR，查看验证通过，来确认流水线正常工作
</success_criteria>
<references>

Composability

可组合能力

  • Verify connection first: Use 
    status
    skill to check TrueFoundry credentials
  • Find workspace FQN: Use 
    workspaces
    skill to get workspace FQNs for your specs
  • Check existing deployments: Use 
    applications
    skill to see what is already deployed
  • Deploy LLM models via GitOps: Use 
    llm-deploy
    skill to generate the manifest YAML, then store it in Git
  • Manage secrets: Use 
    secrets
    skill to set up secret groups referenced in your specs
  • View deployment logs: Use 
    logs
    skill to debug deployments after apply
</references> <troubleshooting>
  • 优先验证连接：使用
    status
    技能检查TrueFoundry凭证
  • 查询工作空间FQN：使用
    workspaces
    技能获取规范所需的工作空间FQN
  • 检查现有部署：使用
    applications
    技能查看已部署的内容
  • 通过GitOps部署LLM模型：使用
    llm-deploy
    技能生成清单YAML，然后存储到Git中
  • 管理密钥：使用
    secrets
    技能创建规范中引用的密钥组
  • 查看部署日志：使用
    logs
    技能调试应用后的部署问题
</references> <troubleshooting>

Error Handling

错误处理

tfy apply Failed — Invalid Spec

tfy apply执行失败 — 规范无效

tfy apply returned a validation error.
Check:
- YAML syntax is valid (no tabs, proper indentation)
- Required fields are present (type, name, workspace_fqn)
- Resource references exist (workspace, secrets, etc.)
Run: tfy apply --file spec.yaml --dry-run
tfy apply returned a validation error.
Check:
- YAML syntax is valid (no tabs, proper indentation)
- Required fields are present (type, name, workspace_fqn)
- Resource references exist (workspace, secrets, etc.)
Run: tfy apply --file spec.yaml --dry-run

tfy apply Failed — Authentication Error

tfy apply执行失败 — 认证错误

401 Unauthorized from tfy apply.
Check:
- TFY_HOST is set correctly (the platform URL, e.g., https://your-org.truefoundry.cloud)
- TFY_API_KEY is valid and not expired
- Secrets are configured correctly in your CI provider
401 Unauthorized from tfy apply.
Check:
- TFY_HOST is set correctly (the platform URL, e.g., https://your-org.truefoundry.cloud)
- TFY_API_KEY is valid and not expired
- Secrets are configured correctly in your CI provider

tfy apply Failed — Workspace Not Found

tfy apply执行失败 — 未找到工作空间

Workspace FQN in the spec does not exist.
Check:
- workspace_fqn field matches an existing workspace
- Use the workspaces skill to list available workspaces
Workspace FQN in the spec does not exist.
Check:
- workspace_fqn field matches an existing workspace
- Use the workspaces skill to list available workspaces

CI Pipeline Not Triggering

CI流水线未触发

Workflow not running on push/PR.
Check:
- File path filters match your YAML file locations
- Branch filters match your default branch name
- CI provider secrets are set (TFY_HOST, TFY_API_KEY)
Workflow not running on push/PR.
Check:
- File path filters match your YAML file locations
- Branch filters match your default branch name
- CI provider secrets are set (TFY_HOST, TFY_API_KEY)

Filename / Spec Name Mismatch

文件名/规范名称不匹配

The YAML filename should match the 'name' field inside the spec.
Example: my-service.yaml should contain name: my-service
This is a convention for clarity — tfy apply uses the internal name, not the filename.
</troubleshooting>
The YAML filename should match the 'name' field inside the spec.
Example: my-service.yaml should contain name: my-service
This is a convention for clarity — tfy apply uses the internal name, not the filename.
</troubleshooting>