> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/tools-and-integrations/github-actions.md).

# GitHub Actions

使用 Edgegap Deploy Action 从 GitHub Actions 部署游戏服务器构建：创建应用版本，在真实部署中进行冒烟测试，并将其推广。

该 [Edgegap 部署操作](https://github.com/edgegap/deploy-action) 在你的工作流推送了新的游戏服务器镜像后，负责发布流程中的 Edgegap 侧操作。

1. **为** 新镜像标签创建一个应用版本。它会从现有版本复制端口、资源、环境变量、最长持续时间和重启策略，因此只更改镜像。Edgegap 会先检查它能否拉取该镜像。
2. **对其进行烟雾测试（可选）。** 它会在你选择的位置附近部署新版本，等待其变为就绪状态，如果服务器在测试窗口内崩溃或重启，则使作业失败。然后它会停止该部署；如果作业被取消，也会一并停止。
3. **将其提升为正式版本（可选）。** 它会将一个现有版本，例如 `prod`，指向新的镜像。你的 [匹配器](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 或后端会继续部署 `prod`，因此无需更改配置即可获得新构建。

每次运行都会写入作业摘要，显示所创建的版本、烟雾测试运行的位置、其端口，以及在失败时服务器的最后几行日志。它还可以记录一个 GitHub Deployment。

## 🚀 快速开始

**先自行创建第一个版本**，可以在仪表盘中、通过插件，或通过 [MCP 集成](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md)来完成，并部署一次以确认它可用。该操作会把该版本的设置复制到之后创建的每个新版本中。

**添加三个仓库密钥：**

| 密钥                          | 获取位置                                                                   |
| --------------------------- | ---------------------------------------------------------------------- |
| `EDGEGAP_API_TOKEN`         | [用户设置 / 令牌](https://app.edgegap.com/user-settings?tab=tokens)          |
| `EDGEGAP_REGISTRY_USERNAME` | [容器注册表](https://app.edgegap.com/registry-management/repositories/list) |
| `EDGEGAP_REGISTRY_TOKEN`    | [容器注册表](https://app.edgegap.com/registry-management/repositories/list) |

{% hint style="info" %}
Edgegap API 从不返回某个版本的注册表登录信息或机密环境变量值，因此该操作无法复制它们。它会将它们作为输入请求，并在创建任何内容之前，如果缺少其中之一就失败。
{% endhint %}

**在镜像构建之后添加该操作：**

```yaml
name: 部署游戏服务器
on:
  push:
    branches: [main]
permissions:
  contents: read
  deployments: write
concurrency: edgegap-deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - id: image
        run: |
          echo "name=registry.edgegap.com/my-project/my-game" >> "$GITHUB_OUTPUT"
          echo "tag=$(date -u +%Y%m%d-%H%M)-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      - uses: docker/login-action@v3
        with:
          registry: registry.edgegap.com
          username: ${{ secrets.EDGEGAP_REGISTRY_USERNAME }}
          password: ${{ secrets.EDGEGAP_REGISTRY_TOKEN }}

      - uses: docker/build-push-action@v6
        with:
          push: true
          platforms: linux/amd64
          tags: ${{ steps.image.outputs.name }}:${{ steps.image.outputs.tag }}

      - uses: edgegap/deploy-action@v0
        with:
          api-token: ${{ secrets.EDGEGAP_API_TOKEN }}
          application: my-game
          image: ${{ steps.image.outputs.name }}
          tag: ${{ steps.image.outputs.tag }}
          registry-username: ${{ secrets.EDGEGAP_REGISTRY_USERNAME }}
          registry-token: ${{ secrets.EDGEGAP_REGISTRY_TOKEN }}
          base-version: prod
          smoke-test: true
          smoke-near: "50.11,8.68"
          promote-version: prod
```

每次构建都要使用唯一的镜像标签，绝不要 `latest`：Edgegap 会按标签缓存镜像。当你不命名新版本时，该操作会按 UTC 时间为其命名（`YYYYMMDD-HHMM`).

## ⚙️ 选项

| 输入                | 默认值     | 用于                           |
| ----------------- | ------- | ---------------------------- |
| `base-version`    | 最新版本    | 选择要复制其设置的版本                  |
| `版本`              | UTC 时间  | 为新版本命名；使用相同名称和镜像重新运行会重用它     |
| `version-secrets` |         | 设置机密环境变量，每个 `KEY=VALUE` 每行一个 |
| `smoke-test`      | `false` | 部署新版本并检查它是否持续运行              |
| `smoke-near`      | 纽约      | 放置测试部署： `纬度,经度` 或一个公共 IP     |
| `smoke-duration`  | `60秒`   | 服务器必须保持就绪且不重启的时长             |
| `startup-timeout` | `5分钟`   | 首次启动最多允许多长时间（大型镜像第一次下载较慢）    |
| `promote-version` |         | 在所有内容都通过后，将一个现有版本指向新镜像       |

该 [该操作的 README](https://github.com/edgegap/deploy-action#inputs) 列出每个输入和输出，包括测试部署的 `fqdn` 和 `端口`。请在后续步骤中使用这些信息运行游戏客户端测试。

## 💡 了解更多

* **回滚** 意味着使用之前的镜像标签和相同的工作流再次运行 `promote-version`.
* **提升只会更改镜像。** 被提升版本的端口、资源和环境变量保持不变。如果构建需要新的设置，请先在仪表盘中更改。
* **烟雾测试是真实部署。** 它大约会按一分钟计费，在免费套餐中会占用你的一个并发部署名额。
* **失败的构建仍然会留下一个版本。** 没有 `promote-version`，除非按名称请求，否则不会有任何东西来部署它。
* **将该操作固定** 到一个发布版本（`edgegap/deploy-action@v0.1.0`）或某个提交 SHA，如果你想在更新获得你的 API token 之前先审查它们。
