Shipyard

官方

Shipyard CLI 提供了一个 MCP 服务器,供智能体直接管理 Shipyard 环境:包括拉取日志、比较分支、运行测试以及停止/启动环境。

你可以用 Shipyard MCP 做什么?

  • 列出环境 — 查询正在运行的环境,可按仓库、分支、拉取请求编号或名称筛选。
  • 检查环境 — 根据 UUID 获取特定环境的详细信息,包括其服务和公开端口。
  • 读取服务日志 — 显示运行中环境内某项服务的日志,也可选择持续跟踪输出。
  • 管理环境生命周期 — 根据 UUID 停止、重启、取消、重建或恢复环境。
  • 配置环境变量 — 在环境中设置环境变量,并重启服务以应用这些变量。
  • 验证已推送的更改 — 使用 verify 提示词检查已推送的更改及其对应环境。

文档

Shipyard CLI

用于管理 Shipyard 平台上的临时环境的工具。

正在使用 AI 助手?CLI 内置了 MCP 服务器:请参阅通过 AI 助手使用 Shipyard。

安装

  • Linux 和 macOS

    curl https://www.shipyard.sh/install.sh | bash
    

    它会安装到 /usr/local/bin;只有在无法写入该目录时才会使用 sudo。若要安装到其他位置,例如你拥有的目录,请设置 SHIPYARD_INSTALL_DIR:

    curl https://www.shipyard.sh/install.sh | SHIPYARD_INSTALL_DIR="$HOME/.local/bin" bash
    
  • Windows 前往发布页面并下载适用于 Windows 的可执行文件。

  • Homebrew

    brew tap shipyard/tap
    brew install shipyard
    

验证下载文件

每个版本都会发布一个 checksums.txt,其中包含每个二进制文件的 SHA-256 值。安装脚本会据此校验二进制文件;如果不匹配,则拒绝安装。若要校验你自行下载的二进制文件:

grep " shipyard-darwin-arm64$" checksums.txt | shasum -a 256 -c -

checksums.txt 与二进制文件来自同一版本,因此它能检测下载文件是否损坏或不完整,但无法检测版本文件是否被替换。下面的证明用于检查二进制文件是否由此仓库的发布工作流构建。

在 1.9.0 之后的版本中,每个二进制文件还附带签名的构建来源证明,说明构建它的工作流运行、提交和标签,以及 SPDX SBOM(shipyard-<os>-<arch>.sbom.json;Windows 上为 .exe.sbom.json),列出构建所用的内容。使用 GitHub CLI 验证证明,并指定你下载的版本(此处为 v1.10.0):

gh attestation verify shipyard-darwin-arm64 -R shipyard/shipyard-cli \
  --signer-workflow shipyard/shipyard-cli/.github/workflows/release.yaml \
  --source-ref refs/tags/v1.10.0

请保留 --source-ref:没有它,任何分支上由该工作流副本签名的内容都会通过检查,而不仅限于该版本标签对应的构建。

检查会指定标签,而不是提交。撤回版本的证明不会被删除,因此如果某个版本以后再次使用相同标签发布,其已撤回的二进制文件仍会通过检查。若要同时固定提交,请添加 --source-digest <commit SHA>,并填入该标签指向的提交。

重新构建发布版本

1.10.0 之后的版本均可复现:使用相同版本的 Go 和 GoReleaser,再次构建发布标签,无论在哪个目录中,都会生成字节完全相同的二进制文件。这些版本分别是该标签的 .github/workflows/release.yaml 中的 GO_VERSION 和 GORELEASER_VERSION。安装好该版本的 GoReleaser,并在下方用 GO_VERSION 替换 1.26.11(GOTOOLCHAIN 会让 Go 严格使用该版本,如有需要会下载它;GOFLAGS= 会移除你自己的构建标志):

git clone https://github.com/shipyard/shipyard-cli && cd shipyard-cli
git checkout vX.Y.Z
GOTOOLCHAIN=go1.26.11 GOFLAGS= goreleaser release --clean --skip=publish,sbom
grep " shipyard-linux-amd64$" dist/checksums.txt

摘要应与该版本的 checksums.txt 中对应行一致。如果不一致,请先检查 Go 和 GoReleaser 的版本(GOTOOLCHAIN=go1.26.11 go version、goreleaser --version),再怀疑发布版本有问题。发布工作流会在每个发布提交上、构建发布版本之前执行此检查(scripts/check-reproducible.sh)。SBOM 无法复现:其中会记录生成时间。CLI 自身模块对应的条目会显示版本 (devel),因为构建时会省略 Go 的 VCS 标记;shipyard --version 会打印发布版本。

升级

shipyard upgrade

shipyard update 执行相同操作。它会安装最新版本并显示其发布说明。通过 Homebrew 安装的版本使用 brew upgrade shipyard 升级;其他安装方式会下载发布二进制文件,根据该版本的 checksums.txt 进行校验,然后替换正在运行的二进制文件。如果该二进制文件位于你无权写入的目录中,例如 /usr/local/bin,请运行 sudo shipyard upgrade。

添加 --prerelease 以包含预发布版本,或添加 --force 以重新安装当前版本(对于 Homebrew 安装,请改用 brew reinstall shipyard)。

从 1.9.0 或更早版本升级

1.9.0 及更早版本中的 shipyard update 会将版本作为文本进行比较,因此会把 1.10.0 及更高版本报告为比你当前版本更旧。请按照原来的安装方式升级一次,此后 shipyard upgrade 就能正常工作:

  • Linux 和 macOS: curl https://www.shipyard.sh/install.sh | bash
  • Windows: 从发布页面下载可执行文件
  • Homebrew: brew upgrade shipyard

更新通知

有新版本发布时,CLI 会在命令执行完毕后告知你,每天最多一次:

A new version of shipyard is available: 1.9.0 → 1.10.0
Run `shipyard upgrade` to install it. Release notes: https://github.com/shipyard/shipyard-cli/releases/tag/v1.10.0

它不会询问任何问题,也不会等待输入。检查会在命令运行期间于后台执行;如果命令结束时检查尚未完成,CLI 最多等待一秒。只有在向 GitHub 查询时才会发生这种情况,大约每天一次,或在获取你错过的发布说明时发生。通过其他方式升级后首次运行时,例如使用 brew upgrade,会显示这些说明。

消息会输出到 stderr,且仅当 stderr 是终端时才会显示。在 CI 中、在会标识自身身份的 AI 编程代理(Claude Code、Codex、Cursor 的 agent、Gemini CLI)中,或在 shipyard mcp serve 中,均不会显示。若要关闭此功能,请设置 SHIPYARD_NO_UPDATE_CHECK=1,或将 update_check: false 添加到 ~/.shipyard/config.yaml。

关闭自动更新

对于无法访问 GitHub 的自托管 Shipyard,CLI 会随 Shipyard 一起发布。在 ~/.shipyard/config.yaml 中设置 self_update: false,或设置 SHIPYARD_SELF_UPDATE=false,即可关闭自动更新。此后 CLI 将不再联系 GitHub:不会显示更新通知,不会从 shipyard mcp serve 在后台检查更新,并且 shipyard upgrade 会提示自动更新已关闭并拒绝执行。update_check: false 只会关闭通知和后台检查。

登录

运行 shipyard login 初始化 CLI。系统会提示你在浏览器中登录 Shipyard。随后 CLI 会将 API 令牌保存到本地配置中。现在即可开始运行命令。

自托管 Shipyard

若要使用自托管的 Shipyard,请在登录前通过 ~/.shipyard/config.yaml(或 SHIPYARD_API_URL)将 CLI 指向其 API:

api_url: https://shipyard.example.internal/api/v1
self_update: false

随后,shipyard login 会打开该主机的登录页面,所有命令也都会调用该 API。如果安装环境无法访问 GitHub,请设置 self_update: false(请参阅关闭自动更新)。

如果你已经登录了另一个 Shipyard(例如 shipyard.build),shipyard login 会保留该令牌,并提示你已登录。在登录自托管安装之前,请从配置文件中移除 api_token(并取消设置 SHIPYARD_API_TOKEN)。

或手动设置令牌

将 Shipyard API 令牌设为环境变量 SHIPYARD_API_TOKEN 的值。

你可以前往个人资料页面获取令牌。

如果你希望为组织启用 API 访问权限,可以通过 support@shipyard.build 联系我们。如有其他问题,欢迎加入我们的社区 Slack。

shipyard set token

你也可以使用配置文件,默认存储在 $HOME/.shipyard/config.yaml 中。首次运行 CLI 时,它会创建一个默认的空配置文件,你可以随后编辑。

你也可以在任何命令中添加 --config {path} 标志,以指定非默认的配置文件路径。

在配置文件中添加所需的配置值,并确保文件符合 YAML 语法。 例如:

api_token: <your-token>
org: <your-non-default-org>

环境变量的值会覆盖配置文件中对应的值。

基本用法

获取你所属的所有组织

shipyard get orgs

设置全局默认组织

shipyard set org {org-name}

获取当前配置的组织

shipyard get org

列出所有环境

shipyard get environments

可用标志:

名称说明类型默认值
branch按分支名称筛选string
deleted返回已删除的环境booleanfalse
json输出完整的 JSONbooleanfalse
name按应用名称筛选string
org-name按组织名称筛选(如果你属于多个组织)string你的默认组织
page请求的页码int1
page-size请求的页面大小int20
pull-request-number按拉取请求编号筛选string
repo-name按仓库名称筛选string

示例:

  • 列出仓库 flask-backend 在分支 main 上运行的所有环境:
shipyard get environments --repo-name flask-backend --branch main
  • 列出所有已删除的环境:
shipyard get environments --deleted

按 UUID 获取特定环境的详细信息

shipyard get environment {environment_uuid}

可用标志:

名称说明类型默认值
json输出完整的 JSONbooleanfalse
org环境所属的组织(如果你属于多个组织)string你的默认组织
bypass-token仅输出环境的绕过令牌,供脚本使用booleanfalse

--bypass-token 允许脚本使用令牌,而无需任何人输入或打印该令牌:

SHIPYARD_TOKEN=$(shipyard get environment {environment_uuid} --bypass-token) && \
  export SHIPYARD_TOKEN && curl -b "shipyard_token=$SHIPYARD_TOKEN" https://your-environment-url/

停止正在运行的环境

shipyard stop environment {environment_uuid}

重启已停止的环境

shipyard restart environment {environment_uuid}

取消环境正在进行的构建

shipyard cancel environment {environment_uuid}

重新构建环境

shipyard rebuild environment {environment_uuid}

恢复已删除的环境

shipyard revive environment {environment_uuid}

部署分离环境

通过克隆现有应用构建,创建一个新的独立(“分离”)环境。 需要为你的组织启用分离环境。

shipyard detached deploy {application_build_uuid} --name my-detached-env

按仓库覆盖分支,并控制分离环境是否在有新提交时重新构建:

# Override the branch for a repo, and never rebuild on new commits
shipyard detached deploy {application_build_uuid} --name my-detached-env --branch web=feature-x --build-on-commit never

# Per-repo build-on-commit settings (always | inherit | never)
shipyard detached deploy {application_build_uuid} --build-on-commit-for web=always --build-on-commit-for api=never

删除分离环境

传入环境 UUID,或其任一应用构建的 UUID(位于构建详情页面的 URL 中)。只有分离环境可以通过此方式删除;基础环境、拉取请求环境或远程环境会被拒绝。再次删除已删除的环境也会成功。

shipyard detached delete {environment_uuid}
shipyard detached delete {application_build_uuid}

获取环境的所有服务和公开端口

shipyard get services --env {environment_uuid}

在正在运行的环境服务中执行命令

在正在运行的环境的指定服务中执行任意命令,并传入任意参数和标志。双斜线之后的内容会作为命令参数传入。只有在你输入内容期间,会话才会阻止环境因空闲而停止,最长可达 12 小时。

shipyard exec --env {environment_uuid} --service {service_name} -- bash

转发正在运行的环境服务端口

shipyard port-forward --env {environment_uuid} --service {service_name} --ports {local_port}:{service_container_port}

打开的 port-forward 或 logs --follow 会阻止环境因空闲而停止,最长可达 12 小时。

获取正在运行的环境服务日志

shipyard logs --env {environment_uuid} --service {service_name}

访问环境

shipyard visit {environment_uuid}

可用标志:

名称说明类型默认值
follow持续输出日志booleanfalse
tail要显示的最近日志行数int3000

使用卷

列出环境中的所有卷

shipyard get volumes --env {environment_uuid}

列出环境中的所有卷快照

shipyard get snapshots --env {environment_uuid}

重置环境中的卷

shipyard reset volume --env {environment_uuid}

在环境中创建快照

shipyard create snapshot --env {environment_uuid}

在环境中加载卷快照

shipyard load snapshot --env {environment_uuid} --sequence-number {n}

将文件上传到环境中的卷

shipyard upload volume --env {environment_uuid} --volume {volume} --file {filepath.bz2}

直接调用 REST API

shipyard api /api/v1/environment
shipyard api -X PUT /api/v1/environment/{environment_uuid}/env-vars --input body.json

路径必须以 /api/v1 或 /api/v2 开头;系统会自动为你添加令牌和组织信息。 除非传入 --include-secrets,否则会对 bypass_token 和 kubeconfig 凭据进行脱敏。

连接到 telepresence

shipyard telepresence connect --env {environment_uuid}

从这里开始,你将能够直接与命名空间中的所有 Pod 通信。你_可能_需要使用命名空间主机名与服务通信,可在 Namespace 字段下通过 telepresence status 获取。例如,要与 redis 通信,你可以使用 redis.shipyard-app-build-{uuid}

从代码构建可执行文件:

运行以下命令即可创建可执行文件:

make

运行这个新可执行文件:

./shipyard

启用自动补全

Bash

此脚本依赖 bash-completion 软件包。如果尚未安装,可以通过操作系统的软件包管理器安装。 要在当前 shell 会话中加载补全:

source <(shipyard completion bash)

要在每个新会话中加载补全,请执行以下命令一次。

在 Linux 上:

shipyard completion bash > /etc/bash_completion.d/shipyard

在 macOS 上:

shipyard completion bash > $(brew --prefix)/etc/bash_completion.d/shipyard

Zsh

如果环境中尚未启用 shell 补全,则需要启用它。执行以下命令一次即可:

echo "autoload -U compinit; compinit" >> ~/.zshrc

要在当前 shell 会话中加载补全:

source <(shipyard completion zsh); compdef _shipyard shipyard

要在每个新会话中加载补全,请执行以下命令一次。

在 Linux 上:

shipyard completion zsh > "${fpath[1]}/_shipyard"

在 macOS 上:

shipyard completion zsh > $(brew --prefix)/share/zsh/site-functions/_shipyard

需要启动新的 shell,此设置才会生效。

Fish

要在当前 shell 会话中加载补全:

$ shipyard completion fish | source

要在每个会话中加载补全,请执行一次:

shipyard completion fish > ~/.config/fish/completions/shipyard.fish

PowerShell

要在当前 shell 会话中加载补全:

shipyard completion powershell | Out-String | Invoke-Expression

要在每个新会话中加载补全,请运行:

shipyard completion powershell > shipyard.ps1

并在 PowerShell 配置文件中加载此文件。

在 AI 助手中使用 Shipyard (MCP)

shipyard mcp serve 运行一个 Model Context Protocol 服务器,因此 Claude Code、Claude Desktop、Cursor 或 Codex 等助手可以列出、检查、重建和配置你的环境,读取服务日志、管理卷,并针对环境验证已推送的更改。

CLI 登录后,将其添加到 Claude Code:

claude mcp add shipyard -- shipyard mcp serve

然后可以提出如下问题:

  • “web 仓库有哪些环境正在运行?”
  • “显示我分支环境中 api 服务的日志。”
  • “此环境的最新构建为什么失败了?”
  • “在此环境中设置 FEATURE_FLAGS=beta,并重启 worker 服务。”
  • “我刚刚推送了更改。针对其环境验证此更改。”(或 /mcp__shipyard__verify)

请参阅 MCP 指南,了解如何在其他客户端中进行设置、配置、完整工具列表、verify 提示词以及故障排除。