> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 蓝图中的 GitHub Actions

> 使用 GitHub Actions 在你的 Devin 环境中安装语言、工具和 SDK，无需编写 shell 脚本。

你无需编写 shell 脚本来安装工具，而是可以直接在蓝图的 `initialize` 或 `maintenance` 部分引用 GitHub Actions。Devin 会在快照构建期间下载并运行该 action，方式与 GitHub 的 CI 运行器执行 action 步骤相同。

这对于 `setup-python`、`setup-node` 和 `setup-go` 这类用于设置语言环境的 action 尤其有用，它们会自动处理版本管理和 PATH 配置。

<div id="syntax">
  ## 语法
</div>

在蓝图的任意部分添加 `uses` 步骤：

```yaml theme={null}
initialize:
  - name: Install Python 3.12
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"
```

| Field  | Type              | Description                                            |
| ------ | ----------------- | ------------------------------------------------------ |
| `name` | string (optional) | 在构建日志中显示的可读标签                                          |
| `uses` | string            | GitHub Action 引用 (参见下方的[格式](#action-reference-format)) |
| `with` | map (optional)    | 传递给该 Action 的输入参数                                      |
| `env`  | map (optional)    | 该步骤的附加环境变量                                             |

<Info>
  一个步骤必须指定 `run` (shell 命令) **或** `uses` (Action) ，二者不能同时指定。
</Info>

<div id="action-reference-format">
  ## 操作引用格式
</div>

```
github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>
```

`github.com/` 前缀和 `@<ref>` 后缀**都必不可少**。ref 通常是类似 `v5` 这样的版本标签。

**示例：**

| Reference                                   | 解析结果                                             |
| ------------------------------------------- | ------------------------------------------------ |
| `github.com/actions/setup-python@v5`        | 标签 `v5` 的 `actions/setup-python`                 |
| `github.com/actions/setup-node@v4`          | 标签 `v4` 的 `actions/setup-node`                   |
| `github.com/gradle/actions/setup-gradle@v4` | `gradle/actions` repo、`setup-gradle` 子目录和标签 `v4` |

<div id="passing-inputs">
  ## 传递输入
</div>

使用 `with` 字段向此 action 传入输入。所有值都会按字符串处理，与 GitHub Actions 的行为一致：

```yaml theme={null}
initialize:
  - uses: github.com/actions/setup-java@v4
    with:
      java-version: "21"
      distribution: "temurin"
```

<Warning>
  始终在 `with` 的值中**用引号括起版本号**。YAML 会将未加引号的 `3.10` 解释为浮点数 `3.1`，这并不是你想要的结果。请改写为 `python-version: "3.10"`。
</Warning>

<div id="setting-environment-variables">
  ## 设置环境变量
</div>

使用 `env` 字段设置仅作用于单个action步骤的环境变量：

```yaml theme={null}
initialize:
  - uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"
    env:
      RUNNER_DEBUG: "1"
```

由某个action设置的环境变量 (通过 `GITHUB_ENV` 或 `GITHUB_PATH`) 会自动传递到蓝图中的后续步骤。

<div id="examples">
  ## 示例
</div>

<div id="python-project-with-a-specific-version">
  ### 使用特定 Python 版本的项目
</div>

```yaml theme={null}
initialize:
  - name: Install Python 3.12
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

maintenance: |
  pip install -r requirements.txt

knowledge:
  - name: test
    contents: pytest
```

<div id="multi-language-project">
  ### 多语言项目
</div>

```yaml theme={null}
initialize:
  - name: Install Node.js
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"
  - name: Install Python
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"
  - name: Install Go
    uses: github.com/actions/setup-go@v5
    with:
      go-version: "1.22"
```

<div id="mixing-actions-with-shell-commands">
  ### 将操作与 shell 命令混合使用
</div>

操作和 shell 命令可以在同一部分中混合使用：

```yaml theme={null}
initialize:
  - name: Install Python
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"
  - name: Install project tools
    run: pip install ruff pytest
  - name: Install Node.js
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"
  - name: Install frontend deps
    run: npm install -g pnpm
```

<div id="java-project-with-gradle">
  ### 使用 Gradle 的 Java 项目
</div>

```yaml theme={null}
initialize:
  - name: Install JDK 21
    uses: github.com/actions/setup-java@v4
    with:
      java-version: "21"
      distribution: "temurin"
  - name: Install Gradle
    uses: github.com/gradle/actions/setup-gradle@v4

maintenance: |
  ./gradlew dependencies

knowledge:
  - name: build
    contents: ./gradlew build
  - name: test
    contents: ./gradlew test
```

<div id="actions-vs-shell-scripts">
  ### Actions 与 shell 脚本
</div>

你不一定要使用 Actions——直接写 shell 命令也完全可行。只有在等效的 shell 脚本会很长或容易出错时，Actions 才更省事。

<Tabs>
  <Tab title="使用 GitHub Actions">
    ```yaml theme={null}
    initialize:
      - uses: github.com/actions/setup-go@v5
        with:
          go-version: "1.23"
    ```
  </Tab>

  <Tab title="等效 shell 脚本">
    ```yaml theme={null}
    initialize: |
      GO_VERSION=1.23.5
      ARCH=$(dpkg --print-architecture)
      curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" \
        | sudo tar -xz -C /usr/local
      echo 'export PATH="/usr/local/go/bin:$HOME/go/bin:$PATH"' \
        | sudo tee /etc/profile.d/golang.sh > /dev/null
    ```
  </Tab>
</Tabs>

<div id="how-it-works">
  ## 工作原理
</div>

当 Devin 在快照构建期间遇到 `uses` 步骤时：

1. **下载** action 代码仓库 (在固定 ref 上进行浅克隆)
2. **读取** action 的 `action.yml` 元数据，以确定运行时和入口点
3. **构建**包含 `INPUT_*`、`GITHUB_*` 和 `RUNNER_*` 变量的执行环境
4. **运行** action 的 `pre` 步骤 (如果已定义) ，然后运行 `main` 入口点
5. **传递**副作用——action 写入 `GITHUB_PATH` 或 `GITHUB_ENV` 的任何条目都会应用到后续的蓝图步骤中

<Info>
  Actions 在真实的 GitHub 工作流程之外运行。像 `github.repository` 这样的上下文变量会被填入占位值。需要实时访问 GitHub API 的 action (例如在 PR 上评论、创建发布) 在蓝图中将无法运行。
</Info>

<div id="limitations">
  ## 限制
</div>

* **仅支持 Node.js Action** — 仅支持使用 Node.js 运行时 (`node16`、`node20`、`node24`) 的 GitHub Actions。不支持基于 Docker 的 Action 和复合 Action。
* **不支持 `post` 生命周期** — Devin 会运行 `pre` 和 `main` 步骤，但会跳过 `post` 清理步骤，因为构建是在一次性 VM 中运行的。
* **GitHub 上下文为占位内容** — 依赖 GitHub API 调用、工作流程事件数据或代码仓库上下文的 Action 可能无法正常工作，因为这些值在构建环境中只是占位内容。
* **固定版本** — 始终引用特定版本标签 (例如 `@v5`) ，而不是分支名称，以确保构建可复现。

<div id="related-pages">
  ## 相关页面
</div>

* [声明式环境配置](/zh/onboard-devin/environment/blueprints)
* [蓝图参考](/zh/onboard-devin/environment/blueprint-reference)
* [模板库](/zh/onboard-devin/environment/templates)