Devin 蓝图模板库

面向常见语言和用例的蓝图，可直接复制粘贴。将它们组合起来，即可构建完整的配置。示例基于 Linux 上的 Bash；请把示例中的主机、作用域和命令替换为你自己的内容。每个字段的详细说明，请参阅蓝图参考。

Secrets： 在每个蓝图编辑器的 Secrets 选项卡中配置具名 secrets。构建步骤会收到适用的蓝图 secrets。在会话期间，请确保每条命令都能拿到所需的 secrets：代码仓库作用域的 secrets 需要显式的 exec 环境绑定，例如 env={"REGISTRY_TOKEN": "secret:repo:owner/repo:REGISTRY_TOKEN"}。参见 Secrets。切勿在蓝图中硬编码凭据。

构建步骤不是会话启动钩子。 initialize 和 maintenance 在构建快照时运行；maintenance 不会在会话启动时自动运行。knowledge 只是向 Devin 提供指示，并非可执行的钩子。不要把凭据留在持久化文件中，包括 $ENVRC。快照清理只会移除 Devin 注入的 secret 文件，不会移除你的命令写入的其他文件。请使用调用凭据的工具所支持的字面量变量引用，或在命令的环境中传入凭据。如果某个工具必须使用凭据文件，请为单次操作创建该文件，并在操作结束前清理掉。在会话中若有需要，再显式重复一次该设置过程。

快速开始

适用于最常见配置的精简蓝图。复制其中一个，粘贴到蓝图编辑器中即可。

Node.js 项目

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

knowledge:
  - name: lint
    contents: |
      运行 `pnpm lint` 检查错误。
  - name: test
    contents: |
      运行 `pnpm test` 执行完整测试套件。

Python 项目

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: |
      运行 `uv run ruff check .` 进行 lint 检查。
  - name: test
    contents: |
      运行 `uv run pytest` 执行完整测试套件。

全栈（Node + Python）

initialize:
  - name: Install pnpm
    run: npm install -g pnpm
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance:
  - name: 前端依赖
    run: (cd frontend && pnpm install)
  - name: 后端依赖
    run: (cd backend && uv sync)

knowledge:
  - name: structure
    contents: |
      - `frontend/` — React 应用（pnpm）
      - `backend/` — Python API（uv）
  - name: test
    contents: |
      前端：cd frontend && pnpm test
      后端：cd backend && uv run pytest

仓库蓝图

按仓库设置的构建步骤、依赖管理和 Knowledge 条目。请在 Settings > Environment > Blueprints > [你的仓库] 中进行设置。

Python

uv（推荐）
pip + venv

适用于使用 uv 进行依赖管理的 Python 项目的推荐设置。

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: |
      uv run ruff check .

      Auto-fix:
      uv run ruff check --fix .

  - name: test
    contents: |
      uv run pytest

  - name: build
    contents: |
      uv run python -m build

使用 pip 和 venv 的传统 Python 设置。项目依赖 requirements.txt 时请使用此配置。

initialize: |
  python3 -m venv .venv

maintenance: |
  source .venv/bin/activate
  pip install -r requirements.txt

knowledge:
  - name: lint
    contents: |
      source .venv/bin/activate
      flake8 .

  - name: test
    contents: |
      source .venv/bin/activate
      pytest

  - name: build
    contents: |
      source .venv/bin/activate
      python -m build

Node.js

npm
pnpm

使用 npm 的标准 Node.js 配置。

initialize: |
  nvm install 20
  nvm use 20

maintenance: |
  npm install

knowledge:
  - name: lint
    contents: |
      npx eslint .

  - name: test
    contents: |
      npm test

  - name: build
    contents: |
      npm run build

在 maintenance 中使用 npm install (不要用 npm ci) 。前者会执行增量更新，而 npm ci 会在每次运行该命令时删除 node_modules，并从头重新安装。

适用于使用 pnpm 的项目。

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install --frozen-lockfile

knowledge:
  - name: lint
    contents: |
      pnpm lint

  - name: test
    contents: |
      pnpm test

  - name: build
    contents: |
      pnpm build

Go

标准 Go 模块配置。

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

  go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

maintenance: |
  go mod download

knowledge:
  - name: lint
    contents: |
      golangci-lint run

  - name: test
    contents: |
      go test ./...

  - name: build
    contents: |
      go build ./...

Java

Gradle
Maven

使用 Gradle 配置 Java 环境。

JDK 17 已预装在 Devin 的基础镜像中。如果默认的 OpenJDK 17 已满足需求，可跳过 JDK 安装步骤。

initialize:
  - name: Install JDK 17
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install Gradle
    run: |
      GRADLE_VERSION=8.12
      curl -fsSL "https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip" \
        -o /tmp/gradle.zip
      sudo unzip -qo /tmp/gradle.zip -d /opt
      sudo ln -sf /opt/gradle-${GRADLE_VERSION}/bin/gradle /usr/local/bin/gradle
      rm /tmp/gradle.zip

maintenance: |
  ./gradlew dependencies

knowledge:
  - name: lint
    contents: |
      ./gradlew check

  - name: test
    contents: |
      ./gradlew test

  - name: build
    contents: |
      ./gradlew build

使用 Maven 配置 Java 环境。

JDK 17 已预装在 Devin 的基础镜像中。如果默认的 OpenJDK 17 已满足需求，可跳过 JDK 安装步骤。

initialize:
  - name: Install JDK 17
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install Maven
    run: |
      MAVEN_VERSION=3.9.9
      curl -fsSL "https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" \
        | sudo tar -xz -C /opt
      sudo ln -sf /opt/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/local/bin/mvn

maintenance: |
  mvn dependency:resolve

knowledge:
  - name: test
    contents: |
      mvn test

  - name: build
    contents: |
      mvn package

Ruby on Rails

基于 PostgreSQL 的 Rails 配置。

initialize:
  - name: Install Ruby 3.3
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ruby-full libpq-dev postgresql-client

maintenance: |
  bundle install
  rails db:migrate

knowledge:
  - name: lint
    contents: |
      bundle exec rubocop

  - name: test
    contents: |
      bundle exec rspec

  - name: build
    contents: |
      rails assets:precompile

Rust

使用 cargo 的标准 Rust 配置。

Rust (通过 rustup) 和 Cargo已预装在 Devin 的基础镜像中。如果默认的稳定工具链已能满足需求，请跳过安装步骤。你只需拉取依赖。

initialize: |
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
  source ~/.cargo/env

maintenance: |
  cargo fetch

knowledge:
  - name: lint
    contents: |
      cargo clippy -- -D warnings

  - name: test
    contents: |
      cargo test

  - name: build
    contents: |
      cargo build --release

Monorepo

多语言
多个 JDK 版本

包含 Node.js 前端和 Python 后端的 Monorepo。每个子项目都有各自的 knowledge 条目。

initialize:
  - name: Install pnpm
    run: npm install -g pnpm
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance:
  - name: Install frontend dependencies
    run: (cd packages/frontend && pnpm install)
  - name: Install backend dependencies
    run: (cd packages/backend && uv sync)
  - name: Build shared library
    run: (cd packages/shared && pnpm install && pnpm build)

knowledge:
  - name: structure
    contents: |
      这是一个包含三个软件包的 monorepo：
      - `packages/frontend` — React 应用（TypeScript、pnpm）
      - `packages/backend` — Python API（FastAPI、uv）
      - `packages/shared` — 共享 TypeScript 工具库（必须先于前端构建）
  - name: frontend
    contents: |
      运行 `cd packages/frontend && pnpm dev` 启动开发服务器。
      运行 `cd packages/frontend && pnpm lint` 执行 lint 检查。
      运行 `cd packages/frontend && pnpm test` 运行测试。
  - name: backend
    contents: |
      运行 `cd packages/backend && uv run uvicorn app.main:app --reload` 启动 API。
      运行 `cd packages/backend && uv run ruff check .` 执行 lint 检查。
      运行 `cd packages/backend && uv run pytest` 运行测试。

使用 subshell (cd dir && command)，不要使用 cd dir && command，这样每个步骤之间都会重置工作目录。

一个 Java Monorepo，其中不同服务需要不同的 JDK 版本。在设置时安装两个 JDK，然后使用 knowledge 条目告诉 Devin 每个服务应使用哪个 JAVA_HOME。

initialize:
  - name: Install JDK 17 (primary)
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install JDK 11 (legacy service)
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-11-jdk-headless

maintenance:
  - name: Warm dependency caches
    run: |
      export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
      (cd services/api && ./gradlew dependencies --refresh-dependencies)

      export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
      (cd services/legacy && ./gradlew dependencies --refresh-dependencies)

knowledge:
  - name: build_api
    contents: |
      构建 API 服务（JDK 17）：
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        cd services/api && ./gradlew clean build
  - name: build_legacy
    contents: |
      构建 legacy 服务（JDK 11）：
        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        cd services/legacy && ./gradlew clean build
  - name: test_all
    contents: |
      运行所有服务的测试：
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        (cd services/api && ./gradlew test)

        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        (cd services/legacy && ./gradlew test)

私有包注册表

配置 package manager，使其从私有包注册表解析依赖。请在 Settings > Environment > Blueprints > Org-wide setup 中进行设置 (若仅有一个代码仓库需要，也可按代码仓库单独配置) 。

存储引用，而非展开后的凭据。 带引号的 heredoc 分隔符 (如 <<'EOF') 会在文件中保留变量引用。npm、Yarn Berry、Maven 和 Gradle 在运行时能够解析下面所示的引用。pip 不会展开 pip.conf 中的 shell 变量，因此请改用环境变量。Shell 配置文件必须与工具在同一条命令中显式 source；不要假定新开的 shell 会自动 source 这些文件或刷新凭据。直接写入持久化配置的 URL (例如 Cargo index、Docker mirror 或 APT mirror) 不得包含凭据。请将身份验证信息单独保存在各模板所示的 secrets 中。如果你此前使用的是会将凭据写入磁盘的旧模板，请删除这些文件，并从干净的基础镜像重建，而不要使用包含这些文件的快照。同时轮换可能已泄露的凭据。

如果你的私有包注册表使用企业 CA，请先确保已在企业级别安装 CA 证书。以下配置假定 HTTPS 信任关系已经建立。

Node.js 注册表

npm（作用域）
npm（完整镜像）
pnpm
Yarn

将 npm 配置为从私有 registry 解析带作用域的软件包 (例如 @myorg/*) ，同时公开软件包仍从默认的 npm registry 获取。

必需的 secrets

GITHUB_PACKAGES_TOKEN — 具有 read:packages 作用域的 Personal access token 或 GitHub App 令牌

maintenance:
  - name: Configure npm scoped registry
    run: |
      npm config set @myorg:registry https://npm.pkg.github.com
      npm config set //npm.pkg.github.com/:_authToken '${GITHUB_PACKAGES_TOKEN}'

将 @myorg 替换为你的 npm 作用域。常见的私有 registry URL：

GitHub Packages: https://npm.pkg.github.com
Artifactory: https://artifactory.example.com/artifactory/api/npm/npm-virtual
Nexus: https://nexus.example.com/repository/npm-group
GitLab: https://gitlab.example.com/api/v4/packages/npm
AWS CodeArtifact: https://<domain>.d.codeartifact.<region>.amazonaws.com/npm/<repo>

让所有 npm 软件包都通过你的私有 registry (而不仅仅是带作用域的软件包) 。

必需的 secrets

NPM_REGISTRY_URL — 你的 npm registry 的完整 URL (例如 https://artifactory.example.com/artifactory/api/npm/npm-virtual)
NPM_REGISTRY_HOST — 仅主机名，不含协议 (例如 artifactory.example.com)
REGISTRY_TOKEN — 该 registry 的 npm 身份验证令牌

maintenance:
  - name: Configure npm to use private registry
    run: |
      npm config set registry '${NPM_REGISTRY_URL}'
      npm config set "//${NPM_REGISTRY_HOST}/:_authToken" '${REGISTRY_TOKEN}'
      npm config set strict-ssl true

将 pnpm 配置为从私有 registry 解析软件包。

必需的 secrets

NPM_REGISTRY_URL — 你的 npm registry 的完整 URL
NPM_REGISTRY_HOST — 仅主机名，不含协议
REGISTRY_TOKEN — 该 registry 的 npm 身份验证令牌

initialize:
  - name: Install pnpm
    run: npm install -g pnpm

maintenance:
  - name: Configure pnpm for private registry
    run: |
      npm config set registry '${NPM_REGISTRY_URL}'
      npm config set "//${NPM_REGISTRY_HOST}/:_authToken" '${REGISTRY_TOKEN}'

将 Yarn (Classic v1 或 Berry v2+) 配置为从私有 registry 解析软件包。

必需的 secrets

NPM_REGISTRY_URL — 你的 npm/Yarn registry 的完整 URL
REGISTRY_TOKEN — 该 registry 的身份验证令牌

Yarn Classic (v1)：

initialize:
  - name: Install Yarn Classic
    run: npm install -g yarn

maintenance:
  - name: Configure Yarn for private registry
    run: |
      npm config set registry '${NPM_REGISTRY_URL}'
      npm config set //registry.example.com/:_authToken '${REGISTRY_TOKEN}'

将 registry.example.com 替换为你的 registry 主机。Yarn Classic 会读取 npm 的 .npmrc。Yarn Berry (v2+)：

maintenance:
  - name: Configure Yarn Berry for private registry
    run: |
      yarn config set npmRegistryServer '${NPM_REGISTRY_URL}'
      yarn config set npmAuthToken '${REGISTRY_TOKEN}'
      # 对于带作用域的软件包：
      # yarn config set npmScopes.myorg.npmRegistryServer "https://npm.pkg.github.com"
      # yarn config set npmScopes.myorg.npmAuthToken '${GITHUB_PACKAGES_TOKEN}'

Python 软件包注册表

pip / uv
Poetry

配置 pip 和 uv，使其从你的私有 PyPI registry (例如 Nexus、Artifactory) 解析软件包。

必需的 secrets

PYPI_REGISTRY_URL — 你的 PyPI 索引完整 URL，如有需要请包含凭据 (例如 https://user:token@nexus.example.com/repository/pypi-proxy/simple)

maintenance:
  - name: Configure pip/uv for private registry
    run: |
      mkdir -p ~/.config
      cat > ~/.config/private-pypi.sh <<'EOF'
      export PIP_INDEX_URL="$PYPI_REGISTRY_URL"
      export UV_INDEX_URL="$PYPI_REGISTRY_URL"
      EOF

knowledge:
  - name: private_python_packages
    contents: |
      With PYPI_REGISTRY_URL available in the command's environment, run:
        source ~/.config/private-pypi.sh && uv sync
      Or:
        source ~/.config/private-pypi.sh && pip install -r requirements.txt

若要在 build 期间预热依赖，请在配置步骤之后向 maintenance 添加相同的 source ... && 命令。URL 凭据中的特殊字符需进行百分号编码。

常见的 PyPI registry URL 模式：

Artifactory: https://artifactory.example.com/artifactory/api/pypi/pypi-virtual/simple
Nexus: https://nexus.example.com/repository/pypi-proxy/simple
AWS CodeArtifact: https://aws:TOKEN@domain-owner.d.codeartifact.region.amazonaws.com/pypi/repo/simple/
Azure Artifacts: https://pkgs.dev.azure.com/org/project/_packaging/feed/pypi/simple
GitLab: https://gitlab.example.com/api/v4/groups/<group-id>/-/packages/pypi/simple

配置 Poetry，使其从私有 PyPI registry 解析软件包。

必需的 secrets

POETRY_REGISTRY_URL — 你的 PyPI 兼容 registry 的完整 URL
REGISTRY_USER — registry 用户名
REGISTRY_PASS — registry 密码或 API 令牌

initialize:
  - name: Install Poetry
    run: curl -sSL https://install.python-poetry.org | python3 -

maintenance:
  - name: Configure Poetry for private registry
    run: |
      poetry config repositories.private "$POETRY_REGISTRY_URL"
      mkdir -p ~/.config
      cat > ~/.config/private-poetry.sh <<'EOF'
      export POETRY_HTTP_BASIC_PRIVATE_USERNAME="$REGISTRY_USER"
      export POETRY_HTTP_BASIC_PRIVATE_PASSWORD="$REGISTRY_PASS"
      EOF

knowledge:
  - name: private_poetry_packages
    contents: |
      With REGISTRY_USER and REGISTRY_PASS available, run:
        source ~/.config/private-poetry.sh && poetry install

安装依赖时，还需在项目的 pyproject.toml 中声明 private 软件包 source。poetry config repositories.private 配置的是发布用仓库；环境凭据将应用于同名的 source。

JVM 软件包注册表

Maven
Gradle

安装 JDK，并将 Maven 配置为通过你的私有 registry (例如 Artifactory、Nexus) 镜像所有依赖解析。

JDK 17 已在 Devin 的基础镜像中预装。如果默认的 OpenJDK 17 足够使用，请跳过安装步骤。你只需安装 Maven 并配置 registry。

必需的 secrets

MAVEN_REGISTRY_URL — 你的 Maven registry URL (例如 https://artifactory.example.com/artifactory/maven-virtual)
REGISTRY_USER — registry 用户名
REGISTRY_PASS — registry 密码或 API 令牌

initialize:
  - name: Install JDK 17
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install Maven
    run: |
      MAVEN_VERSION=3.9.9
      curl -fsSL "https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" \
        | sudo tar -xz -C /opt
      sudo ln -sf /opt/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/local/bin/mvn

maintenance:
  - name: Configure Maven for private registry
    run: |
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <mirrors>
          <mirror>
            <id>private-registry</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.MAVEN_REGISTRY_URL}</url>
          </mirror>
        </mirrors>
        <servers>
          <server>
            <id>private-registry</id>
            <username>${env.REGISTRY_USER}</username>
            <password>${env.REGISTRY_PASS}</password>
          </server>
        </servers>
      </settings>
      EOF

Maven 常见的注册表 URL 模式：

Artifactory: https://artifactory.example.com/artifactory/maven-virtual
Nexus: https://nexus.example.com/repository/maven-public
Azure Artifacts: https://pkgs.dev.azure.com/org/project/_packaging/feed/maven/v1
GitHub Packages: https://maven.pkg.github.com
GitLab: https://gitlab.example.com/api/v4/groups/<group-id>/-/packages/maven
AWS CodeArtifact: https://<domain>.d.codeartifact.<region>.amazonaws.com/maven/<repo>

安装 JDK，并配置 Gradle 以通过你的私有仓库解析所有依赖。

Devin 的基础镜像已预装 JDK 17。如果默认版本已足够，请跳过 JDK 安装步骤。

必需的 secrets

GRADLE_REGISTRY_URL — 你的 Gradle/Maven 仓库 URL
REGISTRY_USER — 仓库用户名
REGISTRY_PASS — 仓库密码或 API 令牌

initialize:
  - name: Install JDK 17
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install Gradle
    run: |
      GRADLE_VERSION=8.12
      curl -fsSL "https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip" \
        -o /tmp/gradle.zip
      sudo unzip -qo /tmp/gradle.zip -d /opt
      sudo ln -sf /opt/gradle-${GRADLE_VERSION}/bin/gradle /usr/local/bin/gradle
      rm /tmp/gradle.zip

maintenance:
  - name: Configure Gradle for private registry
    run: |
      mkdir -p ~/.gradle
      cat > ~/.gradle/init.gradle <<'EOF'
      allprojects {
          repositories {
              maven {
                  url System.getenv("GRADLE_REGISTRY_URL")
                  credentials {
                      username = System.getenv("REGISTRY_USER")
                      password = System.getenv("REGISTRY_PASS")
                  }
                  allowInsecureProtocol = false
              }
          }
      }
      EOF

其他软件包注册表

Go 模块代理

安装 Go，并将其配置为通过私有 module 代理 (例如 Athens、Artifactory 或某个 GOPROXY 端点) 解析 module。

必需的 secrets

GO_PROXY_URL — 你的 Go module 代理的 URL (例如 https://athens.corp.internal)

通过 Git 集成连接 Git provider，并授予其访问托管你私有 module 的仓库的权限。使用普通的 HTTPS Git URL，并配合 Devin 已配置的身份验证。不要在 Git URL 重写规则中嵌入令牌。

initialize:
  - name: Install Go
    run: |
      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

  - name: Configure Go for private modules
    run: |
      cat << 'GOENV' | sudo tee /etc/profile.d/go-private.sh > /dev/null
      export GOPROXY="$GO_PROXY_URL,direct"
      export GONOSUMCHECK="corp.internal/*,github.com/myorg/*"
      export GOPRIVATE="corp.internal/*,github.com/myorg/*"
      GOENV

knowledge:
  - name: private_go_modules
    contents: |
      From the repository root, with GO_PROXY_URL available, run:
        source /etc/profile.d/go-private.sh && go mod download

若要在构建期间预热模块缓存，请将该命令添加到代码仓库蓝图的 maintenance 中，那里可以访问到 go.mod。请勿在组织级设置 (org-wide setup) 中运行该命令，因为它会在仓库克隆之前执行。

常见的 Go 代理 URL 格式：

Artifactory： https://artifactory.example.com/artifactory/go-virtual
Nexus： https://nexus.example.com/repository/go-proxy
Athens： https://athens.corp.internal

.NET / NuGet

配置 NuGet 从私有源解析软件包。

必需的 secrets

NUGET_SOURCE_URL — 你的 NuGet 源的 URL
NuGetPackageSourceCredentials_private — 采用 NuGet 环境变量格式的源凭据：Username=any;Password=<PAT> (使用你的源所要求的用户名)

initialize:
  - name: Install .NET SDK
    run: |
      curl -fsSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 8.0
      echo 'export PATH="$HOME/.dotnet:$PATH"' \
        | sudo tee /etc/profile.d/dotnet.sh > /dev/null

maintenance:
  - name: Configure NuGet for private feed
    run: |
      dotnet nuget add source "$NUGET_SOURCE_URL" \
        --name private 2>/dev/null || \
      dotnet nuget update source private \
        --source "$NUGET_SOURCE_URL"

knowledge:
  - name: private_nuget_packages
    contents: |
      Run dotnet restore with NuGetPackageSourceCredentials_private in its
      environment. The suffix must match the source name "private".

Docker

配置 Docker 从私有容器注册表拉取镜像。Docker login 会将凭据写入其配置目录。请为每次操作使用独立的目录，即使拉取失败也要将其删除。如果在同一会话中还需要拉取其他镜像，请重新执行一次登录并拉取的流程。

必需的 secrets

DOCKER_MIRROR_URL (可选) — 你的 Docker Hub 镜像源 URL (例如 https://mirror.corp.internal)
DOCKER_REGISTRY_URL — 你的私有容器注册表 URL (例如 registry.corp.internal:5000)
DOCKER_REGISTRY_USER — 注册表用户名
DOCKER_REGISTRY_PASS — 注册表密码或 API 令牌

initialize:
  - name: Create Docker config directory
    run: sudo mkdir -p /etc/docker

maintenance:
  - name: Configure Docker for private registry
    run: |
      # 配置 registry mirror（可选 —— 让 Docker Hub 的拉取请求经由你的 registry 进行）
      cat << EOF | sudo tee /etc/docker/daemon.json > /dev/null
      {
        "registry-mirrors": ["$DOCKER_MIRROR_URL"]
      }
      EOF
      sudo systemctl restart docker || true

knowledge:
  - name: private_container_images
    contents: |
      With the registry secrets available, run this in one shell.
      Replace team/image:tag with the image to pull:
        (
          set -euo pipefail
          umask 077
          DOCKER_CONFIG=$(mktemp -d)
          export DOCKER_CONFIG
          trap 'rm -rf "$DOCKER_CONFIG"' EXIT
          printf '%s' "$DOCKER_REGISTRY_PASS" |
            docker login "$DOCKER_REGISTRY_URL" \
              --username "$DOCKER_REGISTRY_USER" --password-stdin
          docker pull "$DOCKER_REGISTRY_URL/team/image:tag"
        )

若要将镜像缓存到快照中，请在构建步骤中放入完整的同一段子 shell。不要把登录和清理拆分到不同步骤，并在生成镜像前确认清理已成功完成。注册表镜像源 URL 中不得包含凭据。

常见的容器注册表 URL：

Amazon ECR： <account-id>.dkr.ecr.<region>.amazonaws.com
Azure Container Registry： <name>.azurecr.io
Google Artifact Registry： <region>-docker.pkg.dev
GitHub Container Registry： ghcr.io
GitLab Container Registry： registry.gitlab.example.com
Nexus： https://nexus.example.com:8443
JFrog： <name>.jfrog.io

Rust / Cargo

配置 Cargo 以从 private registry 解析 crates。

Rust (通过 rustup) 与 Cargo 已预装在 Devin 的基础 image 中。如果 default 的 stable 工具链已经够用，可跳过安装步骤,你只需完成 registry 配置。

必需的 secrets

CARGO_REGISTRY_INDEX — private registry 索引的 URL (例如 sparse+https://cargo.corp.internal/api/v1/crates/)
CARGO_REGISTRIES_PRIVATE_TOKEN — 名为 private 的 registry 的身份验证令牌

initialize:
  - name: Install Rust
    run: |
      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
        | sh -s -- -y --default-toolchain stable
      echo 'source "$HOME/.cargo/env"' \
        | sudo tee /etc/profile.d/rust.sh > /dev/null

maintenance:
  - name: Configure Cargo for private registry
    run: |
      mkdir -p ~/.cargo
      cat > ~/.cargo/config.toml << EOF
      [registry]
      global-credential-providers = ["cargo:token"]

      [registries.private]
      index = "$CARGO_REGISTRY_INDEX"

      [source.crates-io]
      replace-with = "private"

      [source.private]
      registry = "$CARGO_REGISTRY_INDEX"
      EOF

knowledge:
  - name: private_rust_packages
    contents: |
      Run cargo fetch with CARGO_REGISTRIES_PRIVATE_TOKEN in its environment.

registry 索引 URL 不得包含凭据。Cargo 的 cargo:token 提供商会从环境中读取指定 registry 的令牌；请勿在构建步骤中运行 cargo login。

如果你只是想添加一个私有 registry，而不替换 crates.io，请删除 [source.crates-io] 和 [source.private] 小节，改用 cargo install --registry private，或在 Cargo.toml 中写入 [dependencies] my-crate = { version = "1.0", registry = "private" }。

Ruby / Bundler

安装 Ruby 并配置 Bundler，使其从私有 gem 服务器解析 gem。

必需的 secrets

GEM_SERVER_URL — 你的私有 gem 服务器的 URL (例如 https://artifactory.example.com/artifactory/api/gems/gems-virtual)
BUNDLE_ARTIFACTORY__EXAMPLE__COM — 用于 artifactory.example.com 的 username:password；请将变量名改为与你的 gem 服务器相匹配

initialize:
  - name: Install Ruby
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ruby-full

maintenance:
  - name: Configure Bundler for private gem server
    run: |
      bundle config set mirror.https://rubygems.org "$GEM_SERVER_URL"

knowledge:
  - name: private_ruby_packages
    contents: |
      Run bundle install with BUNDLE_ARTIFACTORY__EXAMPLE__COM in its environment.

使用不含凭据的 GEM_SERVER_URL。对于 Bundler 的凭据变量，请将 hostname 转为大写并加上 BUNDLE_ 前缀，同时把每个点替换为 __，每个连字符替换为 ___。

常见的 gem server URL 形式：

Artifactory： https://artifactory.example.com/artifactory/api/gems/gems-virtual
Nexus： https://nexus.example.com/repository/rubygems-proxy
Gemfury： https://gem.fury.io/<org>

PHP / Composer

安装 PHP 并配置 Composer，以便从私有 Packagist 或 Satis registry 解析软件包。

必需的 secrets

COMPOSER_REGISTRY_URL — 你的私有 Composer registry 的 URL (例如 https://repo.packagist.com/<org>)
COMPOSER_AUTH — 该 registry 主机的 JSON 凭据，例如 {"http-basic":{"repo.packagist.com":{"username":"<user>","password":"<token>"}}}

initialize:
  - name: Install PHP and Composer
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq \
        php-cli php-mbstring php-xml php-curl unzip

      # 安装 Composer
      curl -sS https://getcomposer.org/installer | php
      sudo mv composer.phar /usr/local/bin/composer

maintenance:
  - name: Configure Composer for private registry
    run: |
      composer config --global repositories.private \
        composer "$COMPOSER_REGISTRY_URL"

knowledge:
  - name: private_php_packages
    contents: |
      Run composer install with COMPOSER_AUTH in its environment.
      Do not save these credentials to auth.json.

使用不含凭据的 COMPOSER_REGISTRY_URL。

常见的 Composer registry URL 形式：

Artifactory： https://artifactory.example.com/artifactory/api/composer/packagist-virtual
Nexus： https://nexus.example.com/repository/packagist-proxy
Private Packagist： https://repo.packagist.com/<org>
Satis： https://satis.corp.internal

AWS CodeArtifact 令牌刷新

AWS CodeArtifact 令牌通常在 12 小时后过期。请创建一个包含字面引用的脚本，然后在运行 npm、pip 或 Maven 的同一条 shell 命令中显式 source 该脚本来获取令牌。将脚本保存在蓝图中并不会在会话启动时自动执行它。

Devin 的基础 image 上已预装 awscli。你只需完成令牌刷新和 registry 配置。

必需的 secrets

AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY — 具备 codeartifact:GetAuthorizationToken 和 sts:GetServiceBearerToken 权限的 IAM 凭据
CA_DOMAIN — 你的 CodeArtifact 域名
CA_DOMAIN_OWNER — 拥有该域的 AWS 账户 ID
CA_REGION — AWS 区域 (例如 us-east-1)
CA_NPM_REPO、CA_PYPI_REPO、CA_MAVEN_REPO — 各生态对应的代码仓库名称

maintenance:
  - name: Configure CodeArtifact clients and refresh script
    run: |
      mkdir -p ~/.config
      cat > ~/.config/codeartifact.sh <<'SCRIPT'
      CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
        --domain "$CA_DOMAIN" \
        --domain-owner "$CA_DOMAIN_OWNER" \
        --region "$CA_REGION" \
        --query authorizationToken \
        --output text) || return
      export CODEARTIFACT_AUTH_TOKEN
      export CA_ENDPOINT="https://${CA_DOMAIN}-${CA_DOMAIN_OWNER}.d.codeartifact.${CA_REGION}.amazonaws.com"
      export PIP_INDEX_URL="https://aws:${CODEARTIFACT_AUTH_TOKEN}@${CA_DOMAIN}-${CA_DOMAIN_OWNER}.d.codeartifact.${CA_REGION}.amazonaws.com/pypi/${CA_PYPI_REPO}/simple/"
      SCRIPT

      # 配置 npm
      npm config set registry '${CA_ENDPOINT}/npm/${CA_NPM_REPO}/'
      npm config set "//${CA_DOMAIN}-${CA_DOMAIN_OWNER}.d.codeartifact.${CA_REGION}.amazonaws.com/npm/${CA_NPM_REPO}/:_authToken" '${CODEARTIFACT_AUTH_TOKEN}'

      # 配置 Maven（可选）
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <servers>
          <server>
            <id>codeartifact</id>
            <username>aws</username>
            <password>${env.CODEARTIFACT_AUTH_TOKEN}</password>
          </server>
        </servers>
        <mirrors>
          <mirror>
            <id>codeartifact</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.CA_ENDPOINT}/maven/${env.CA_MAVEN_REPO}/</url>
          </mirror>
        </mirrors>
      </settings>
      EOF

knowledge:
  - name: codeartifact_packages
    contents: |
      With AWS credentials and the CA_* variables available, run the appropriate
      command in one shell; source the script again for later invocations:
        source ~/.config/codeartifact.sh && npm install
        source ~/.config/codeartifact.sh && pip install -r requirements.txt
        source ~/.config/codeartifact.sh && mvn dependency:resolve

若要在快照中预热依赖缓存，请将相应的 source ... && 命令添加为后续的构建步骤。获取到的令牌仅存在于该 shell 的环境中；请勿通过 aws codeartifact login、使用已展开令牌的 npm config set 或包含凭据的 pip.conf 将其持久化。

企业基础架构

适用于所有组织和代码仓库的机器级基础架构。可在 Settings > Devin’s base environment (企业范围) 或 Settings > Environment > Blueprints > Org-wide setup (组织范围) 中进行设置。

网络与连接

企业级 CA 证书

你的组织为内部服务使用私有证书颁发机构 (CA) 。Devin 需要根证书，才能通过 HTTPS 访问内部制品库和工具。

必需的 secrets

CORP_ROOT_CA_B64 — 来自你的企业 CA 的 Base64 编码 PEM 证书。可使用以下命令生成：cat corp-root-ca.crt | base64 -w0

initialize:
  - name: Install corporate CA certificate
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      sudo update-ca-certificates
      echo 'export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt' \
        | sudo tee /etc/profile.d/node-ca.sh > /dev/null

这些输入是公共证书。openssl x509 只会写出解析后的证书，因此即便其中不慎包含了私钥，也不会被复制到信任存储中。请参照下一个示例，分别提供每个 CA 证书。

多个 CA 证书

如果你的组织使用多个 CA 证书 (例如，不同的内部服务分别使用不同的 CA) 。

必需的 secrets

CORP_ROOT_CA_B64 — Base64 编码的主 CA 证书
CORP_INTERMEDIATE_CA_B64 — Base64 编码的中间 CA 证书

initialize:
  - name: Install corporate CA certificates
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      printf '%s' "$CORP_INTERMEDIATE_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-intermediate-ca.crt > /dev/null
      sudo update-ca-certificates

      # 为需要单个 CA 文件的工具创建合并包
      cat /usr/local/share/ca-certificates/corp-*.crt \
        | sudo tee /usr/local/share/ca-certificates/corp-bundle.crt > /dev/null

      echo 'export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-bundle.crt' \
        | sudo tee /etc/profile.d/node-ca.sh > /dev/null

HTTP/HTTPS 代理

使所有网络流量都通过企业代理转发。

必需的 secrets

CORP_HTTP_PROXY — HTTP 代理 URL (例如：http://proxy.corp.example.com:8080)
CORP_HTTPS_PROXY — HTTPS 代理 URL
CORP_NO_PROXY — 以逗号分隔的绕过代理的主机列表 (例如：localhost,127.0.0.1,.corp.example.com)

initialize:
  - name: Configure system-wide proxy
    run: |
      cat << 'PROXY' | sudo tee /etc/profile.d/proxy.sh > /dev/null
      export http_proxy="$CORP_HTTP_PROXY"
      export https_proxy="$CORP_HTTPS_PROXY"
      export no_proxy="$CORP_NO_PROXY"
      export HTTP_PROXY="$CORP_HTTP_PROXY"
      export HTTPS_PROXY="$CORP_HTTPS_PROXY"
      export NO_PROXY="$CORP_NO_PROXY"
      PROXY
      source /etc/profile.d/proxy.sh

knowledge:
  - name: proxy_commands
    contents: |
      With CORP_HTTP_PROXY, CORP_HTTPS_PROXY and CORP_NO_PROXY available, source
      the proxy setup in each command that needs it, for example:
        source /etc/profile.d/proxy.sh && npm install
        source /etc/profile.d/proxy.sh && git fetch

身份验证代理

如果你的企业代理需要通过用户名/密码进行身份验证。

必需的 secrets

PROXY_USER — 代理用户名
PROXY_PASS — 代理密码
PROXY_HOST — 代理主机名和端口 (例如 proxy.corp.example.com:8080)
CORP_NO_PROXY — 不经代理的主机

initialize:
  - name: Configure authenticated proxy
    run: |
      cat <<'PROXY' | sudo tee /etc/profile.d/proxy.sh > /dev/null
      export http_proxy="http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}"
      export https_proxy="$http_proxy"
      export no_proxy="$CORP_NO_PROXY"
      export HTTP_PROXY="$http_proxy"
      export HTTPS_PROXY="$https_proxy"
      export NO_PROXY="$CORP_NO_PROXY"
      PROXY
      source /etc/profile.d/proxy.sh

knowledge:
  - name: authenticated_proxy_commands
    contents: |
      With the proxy secrets available, source the proxy setup in the same
      command as each tool that needs it, for example:
        source /etc/profile.d/proxy.sh && git fetch

请对代理用户名和密码中的特殊字符进行百分号编码。Git 和 npm 可以使用代理环境变量；不要将包含凭据的代理 URL 写入它们的持久化配置中。

CA 证书 + 代理（组合）

适用于同时需要 corporate CA 和代理的环境的组合配置。这在 Enterprise 环境中很常见：内部服务使用私有证书，且所有流量都必须通过代理转发。

必需的 secrets

CORP_ROOT_CA_B64 — Base64 编码的 corporate CA certificate
CORP_HTTP_PROXY, CORP_HTTPS_PROXY — 代理 URL
CORP_NO_PROXY — 不走代理的主机

initialize:
  - name: Install corporate CA certificate
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      sudo update-ca-certificates
      echo 'export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt' \
        | sudo tee /etc/profile.d/node-ca.sh > /dev/null

  - name: Configure system-wide proxy
    run: |
      cat << 'PROXY' | sudo tee /etc/profile.d/proxy.sh > /dev/null
      export http_proxy="$CORP_HTTP_PROXY"
      export https_proxy="$CORP_HTTPS_PROXY"
      export no_proxy="$CORP_NO_PROXY"
      export HTTP_PROXY="$CORP_HTTP_PROXY"
      export HTTPS_PROXY="$CORP_HTTPS_PROXY"
      export NO_PROXY="$CORP_NO_PROXY"
      PROXY
      source /etc/profile.d/proxy.sh

knowledge:
  - name: proxy_commands
    contents: |
      With the proxy secrets available, run:
        source /etc/profile.d/proxy.sh && git fetch

VPN 连接

你的私有仓库、Git 服务器或其他内部服务只能通过 VPN 访问。请在蓝图中安装 VPN 客户端。仅在需要的操作中显式建立隧道，并在完成后断开连接并删除凭据文件。

必需的 secrets

OpenVPN：

VPN_CONFIG_B64 — 经过 Base64 编码的 OpenVPN 配置文件 (.ovpn) 。生成方式：cat corp.ovpn | base64 -w0
VPN_AUTH_USER (可选) — VPN 用户名 (如果你的 VPN 需要用户名/密码认证)
VPN_AUTH_PASS (可选) — VPN 密码

WireGuard：

WG_CONFIG_B64 — 经过 Base64 编码的 WireGuard 配置文件。生成方式：cat wg0.conf | base64 -w0

OpenVPN：

initialize:
  - name: Install OpenVPN
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openvpn

在具备 VPN secrets 的会话中显式运行此块。将 curl 命令替换为需要通过该隧道完成的工作。配置中必须以 inline 方式包含所需的证书和密钥，并使用 dev tun0；请勿启用常驻的 VPN 服务。

(
  set -euo pipefail
  umask 077
  VPN_DIR=$(mktemp -d)
  cleanup() {
    if [ -f "$VPN_DIR/openvpn.pid" ]; then
      sudo kill "$(cat "$VPN_DIR/openvpn.pid")" || true
    fi
    sudo rm -rf "$VPN_DIR"
  }
  trap cleanup EXIT
  printf '%s' "$VPN_CONFIG_B64" | base64 -d > "$VPN_DIR/corp.conf"
  if [ -n "${VPN_AUTH_USER:-}" ] && [ -n "${VPN_AUTH_PASS:-}" ]; then
    printf '%s\n%s\n' "$VPN_AUTH_USER" "$VPN_AUTH_PASS" > "$VPN_DIR/auth.txt"
    printf 'auth-user-pass %s/auth.txt\n' "$VPN_DIR" >> "$VPN_DIR/corp.conf"
  fi
  sudo openvpn --config "$VPN_DIR/corp.conf" \
    --writepid "$VPN_DIR/openvpn.pid" --daemon
  for i in $(seq 1 30); do
    if ip link show tun0 >/dev/null 2>&1; then break; fi
    sleep 1
  done
  ip link show tun0 >/dev/null
  curl --fail https://service.corp.internal/health
)

WireGuard：

initialize:
  - name: Install WireGuard
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq wireguard-tools

在 WG_CONFIG_B64 可用的情况下显式运行此块，并将 curl 命令替换为你的操作：

(
  set -euo pipefail
  umask 077
  VPN_DIR=$(mktemp -d)
  cleanup() {
    sudo wg-quick down "$VPN_DIR/corp.conf" || true
    sudo rm -rf "$VPN_DIR"
  }
  trap cleanup EXIT
  printf '%s' "$WG_CONFIG_B64" | base64 -d > "$VPN_DIR/corp.conf"
  sudo wg-quick up "$VPN_DIR/corp.conf"
  curl --fail https://service.corp.internal/health
)

如果 snapshot build 需要 VPN 访问，请将所有依赖工作放在同一个块中，以便在生成镜像前完成清理。仅仅把凭据写入操作移到 maintenance 并不会使其变为临时性的。不要对处于 active 状态的 tunnel 或 private VPN 配置制作 snapshot。

有关 VPN 设置的更多信息，请参阅 VPN configuration。

自定义 DNS 解析

你的内部服务使用无法通过公共 DNS 解析的私有 DNS 名称。

initialize:
  - name: Configure custom DNS resolution
    run: |
      # 添加内部主机名
      cat << 'HOSTS' | sudo tee -a /etc/hosts > /dev/null
      10.0.1.50  nexus.corp.internal
      10.0.1.51  git.corp.internal
      10.0.1.52  artifactory.corp.internal
      HOSTS

      # 可选：配置自定义域名服务器
      sudo mkdir -p /etc/systemd/resolved.conf.d
      cat << 'DNS' | sudo tee /etc/systemd/resolved.conf.d/corp.conf > /dev/null
      [Resolve]
      DNS=10.0.0.53 10.0.0.54
      Domains=corp.internal
      DNS
      sudo systemctl restart systemd-resolved || true

身份与安全

GPG 提交签名

你的组织要求对所有 Git 提交进行签名，并且你希望 GitHub 将 Devin 的提交标记为 Verified。

必需的 secrets

GPG_PRIVATE_KEY_B64 — Base64 编码的 GPG 私钥。生成方式：gpg --export-secret-keys <key-id> | base64 -w0
GPG_SIGNING_KEY — 签名密钥的完整指纹
GIT_USER_NAME — Git 作者名称 (例如 Devin AI)
GIT_USER_EMAIL — Git 作者邮箱。必须与 GPG 密钥上的某个 UID 匹配，否则 GitHub 不会验证签名。

同时请将配对的公钥上传到 Devin 推送时所用凭据对应的 GitHub 账户 (位于 GitHub Settings > SSH and GPG keys) 。只有当签名公钥已注册在该提交的作者账户下时，GitHub 才会将提交标记为 Verified。

请勿在快照构建期间导入签名私钥。在暂存好目标更改后，在可访问上述 secrets 的会话中显式运行以下块。它会使用临时密钥环，以及仅对本次提交生效的 Git 设置：

(
  set -euo pipefail
  umask 077
  GNUPGHOME=$(mktemp -d)
  export GNUPGHOME
  trap 'gpgconf --kill gpg-agent; rm -rf "$GNUPGHOME"' EXIT
  printf '%s' "$GPG_PRIVATE_KEY_B64" | base64 -d | gpg --batch --import
  git -c user.name="$GIT_USER_NAME" -c user.email="$GIT_USER_EMAIL" \
    -c user.signingkey="$GPG_SIGNING_KEY" -c commit.gpgsign=true \
    -c gpg.program=gpg commit -m "Describe the change"
)

如果你的密钥需要口令，请在操作过程中完成已批准的 GPG agent/pinentry 流程。请勿将口令或密钥环保存到蓝图或快照中。后续提交或创建签名标签时，请重复上述临时密钥环的设置步骤。

Git 身份与 SSH 密钥

配置 Devin 的 Git 身份，以及用于访问私有 Git 服务器的 SSH 密钥。对于受支持的 Git 提供商，建议优先使用 Git 集成。如果某个服务器必须使用显式的 SSH 密钥，请不要将私钥带入蓝图构建，仅在下面的会话操作中使用。

必需的 secrets

GIT_USER_NAME — Git 作者名称
GIT_USER_EMAIL — Git 作者邮箱
SSH_PRIVATE_KEY_B64 — Base64 编码的 SSH 私钥。生成方式：cat ~/.ssh/id_ed25519 | base64 -w0
SSH_KNOWN_HOSTS_B64 — Base64 编码的 known hosts 条目，需与服务器管理员公布的主机密钥指纹核对验证

initialize:
  - name: Configure git identity
    run: |
      git config --global user.name "$GIT_USER_NAME"
      git config --global user.email "$GIT_USER_EMAIL"

在会话中显式运行以下块，并将其中的 Git URL 替换为你自己的服务器和代码仓库：

(
  set -euo pipefail
  umask 077
  SSH_DIR=$(mktemp -d)
  trap 'rm -rf "$SSH_DIR"' EXIT
  printf '%s' "$SSH_PRIVATE_KEY_B64" | base64 -d > "$SSH_DIR/id_ed25519"
  printf '%s' "$SSH_KNOWN_HOSTS_B64" | base64 -d > "$SSH_DIR/known_hosts"
  export GIT_SSH_COMMAND="ssh -F /dev/null -i '$SSH_DIR/id_ed25519' -o IdentitiesOnly=yes -o UserKnownHostsFile='$SSH_DIR/known_hosts' -o StrictHostKeyChecking=yes"
  git ls-remote git@git.corp.internal:team/repo.git
)

如果需要自定义 SSH 选项，请直接加在这条命令中，不要把私钥复制到持久化的 SSH 配置或主目录中。每次操作都重复执行该设置步骤。

系统配置

系统软件包

安装默认 Devin 镜像中不包含的系统级软件包 (例如，用于图像处理或 PDF 生成的原生库) 。

initialize:
  - name: Install system packages
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq \
        libpq-dev \
        libmagickwand-dev \
        poppler-utils \
        ffmpeg

自定义环境变量

设置在每个会话中都可用的持久、非敏感环境变量。不要将敏感值或派生的凭据写入 $ENVRC。推荐的做法是将 KEY=VALUE 逐行写入 $ENVRC 文件。写入 $ENVRC 的变量会自动导出到后续所有步骤以及 Devin 会话中 (类似于 GitHub Actions 的 $GITHUB_ENV) 。

initialize:
  - name: 设置自定义环境变量
    run: |
      echo "CORPORATE_ENV=production" >> $ENVRC
      echo "DEFAULT_REGION=us-east-1" >> $ENVRC
      echo "MAX_RETRIES=3" >> $ENVRC

你也可以将环境变量写入 /etc/profile.d/ 脚本，使其在整个系统范围内生效：

cat << 'ENVVARS' | sudo tee /etc/profile.d/custom-env.sh > /dev/null
export CORPORATE_ENV=production
export DEFAULT_REGION=us-east-1
ENVVARS

这两种方式都可以。$ENVRC 更简单，也是大多数情况下推荐的做法。

区域设置和时区

默认基础镜像的区域设置可能有误。请配置区域设置和时区，以避免构建工具、Java、Python 和 Git 发出警告。

initialize:
  - name: Configure locale and timezone
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq locales

      # 生成并设置语言环境
      sudo sed -i 's/^# *en_US.UTF-8/en_US.UTF-8/' /etc/locale.gen
      sudo locale-gen
      sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

      cat << 'LOCALE' | sudo tee /etc/profile.d/locale.sh > /dev/null
      export LANG="en_US.UTF-8"
      export LC_ALL="en_US.UTF-8"
      LOCALE

      # 设置时区
      sudo timedatectl set-timezone UTC 2>/dev/null || \
        sudo ln -sfn /usr/share/zoneinfo/UTC /etc/localtime

资源限制（ulimits）

Java、Gradle 和 Node.js 构建经常会达到默认的 1024 个打开文件数限制。请调高该限制，以避免构建失败。

initialize:
  - name: Raise resource limits
    run: |
      cat << 'LIMITS' | sudo tee /etc/security/limits.d/99-devin.conf > /dev/null
      *    soft    nofile    65536
      *    hard    nofile    65536
      *    soft    nproc     65536
      *    hard    nproc     65536
      LIMITS

      # 同时设置内核最大值
      echo "fs.file-max = 65536" | sudo tee /etc/sysctl.d/99-devin-filemax.conf > /dev/null
      sudo sysctl -p /etc/sysctl.d/99-devin-filemax.conf 2>/dev/null || true

替换 APT 镜像源

在隔离或受限环境中，将默认的 Ubuntu APT 软件源替换为内部镜像源。

必需的 secrets

APT_MIRROR_URL — 你的内部 APT 镜像源的 URL (例如：https://artifactory.example.com/artifactory/ubuntu-remote)

initialize:
  - name: Replace APT sources with internal mirror
    run: |
      # 备份原始源
      sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

      # 将所有 Ubuntu 镜像替换为你的内部镜像
      sudo sed -i "s|http://archive.ubuntu.com/ubuntu|$APT_MIRROR_URL|g" /etc/apt/sources.list
      sudo sed -i "s|http://security.ubuntu.com/ubuntu|$APT_MIRROR_URL|g" /etc/apt/sources.list

      sudo apt-get update -qq

常见的 APT 镜像 URL 格式：

Artifactory: https://artifactory.example.com/artifactory/ubuntu-remote
Nexus: https://nexus.example.com/repository/ubuntu-proxy

高级用法

使用 direnv 管理环境变量

Devin 的基础环境中已包含 direnv。使用 initialize 创建 .envrc 文件后，Direnv 会自动加载它们。

initialize: |
  cat <<'EOF' > .envrc
  export DATABASE_URL=postgresql://localhost:5432/myapp_dev
  export REDIS_URL=redis://localhost:6379
  export APP_ENV=development
  EOF

maintenance: |
  direnv allow .

direnv 已预先集成到 Devin 的 shell 中，因此 .envrc 变量会自动加载。无需手动执行 source。

对于敏感环境变量 (API key、令牌、数据库密码) ，请使用 repo secrets，而不是 .envrc 文件，并将它们显式绑定到需要用到它们的会话命令上。在构建过程中把某个 secret 展开写入文件，仍有可能将其带入快照中。

按仓库切换 Node 版本

使用 nvm (已预装) 通过 .nvmrc 为每个仓库切换 Node.js 版本。

initialize: |
  nvm install 18
  nvm install 20
  nvm install 22

maintenance: |
  nvm use

nvm use 会从仓库根目录读取 .nvmrc。请确保你的仓库中包含该文件 (例如内容为 20) 。

浏览器身份验证（Playwright）

在会话期间，Devin 会提供一个 Chrome 浏览器，其 CDP 端点为 localhost:29229。使用 Playwright 脚本可自动完成基于浏览器的登录。

该浏览器仅在会话期间可用，不适用于快照构建。请在 initialize 中安装 Playwright，并将登录脚本保存在你的代码仓库中。

initialize: |
  pip install playwright
  playwright install chromium

maintenance: |
  npm install

knowledge:
  - name: browser-auth
    contents: |
      This project requires browser authentication.
      Run the login script before interacting with the app:
      python scripts/login.py

      Devin's Chrome browser is accessible via CDP at:
      http://localhost:29229

示例登录脚本 (scripts/login.py) ：

from playwright.sync_api import sync_playwright
import os

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://localhost:29229")
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()

    page.goto("https://internal-tool.example.com/login")
    page.fill("#username", os.environ["TOOL_USERNAME"])
    page.fill("#password", os.environ["TOOL_PASSWORD"])
    page.click('button[type="submit"]')
    page.wait_for_url("**/dashboard")

将登录凭据以 secrets 的形式存储，不要写入源代码。对于需要长期保持的身份验证，请将登录脚本提交到 .agents/skills/，以便 Devin 自动重新验证身份。

自定义系统工具与 PATH

在 initialize 中安装系统软件包、自定义二进制文件，并配置 PATH。

initialize:
  - name: Install system packages
    run: |
      apt-get update
      apt-get install -y \
        jq \
        ripgrep \
        fd-find \
        protobuf-compiler \
        libssl-dev

  - name: Install custom CLI tool
    run: |
      curl -L https://github.com/example/tool/releases/download/v1.0/tool-linux-amd64 \
        -o /usr/local/bin/mytool
      chmod +x /usr/local/bin/mytool

  - name: Add custom bin directory to PATH
    run: |
      mkdir -p ~/bin
      echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc

knowledge:
  - name: tools
    contents: |
      Custom tools available:
      - mytool: installed at /usr/local/bin/mytool
      - Additional binaries can be placed in ~/bin

使用 GitHub Actions 设置工具

Devin 支持在蓝图的 initialize 部分中直接运行 GitHub Actions。这对于通过 CI 所使用的同一套 actions 安装特定版本的工具非常有用。

initialize:
  - name: "Install Node.js 20"
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: "Install Python 3.12"
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: "Install Go 1.22"
    uses: github.com/actions/setup-go@v5
    with:
      go-version: "1.22"

  - name: "Install Java 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

  - name: "Install Ruby 3.3"
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: "Install additional tools"
    run: |
      pip install uv
      npm install -g pnpm turbo
      go install golang.org/x/tools/gopls@latest

maintenance: |
  echo "All runtimes are available:"
  node --version
  python --version
  go version
  java --version

setup-node 和 setup-python 这类 action 会修改 PATH 和环境变量。某个 action 安装的二进制文件在后续所有步骤以及 maintenance 中都可用。支持 Node.js 和复合型 action；Docker action 仅在 Linux 构建中受支持。uses 步骤无法在 maintenance 中运行。参见 GitHub Actions 限制。

你无需依赖 GitHub Actions 来完成基础工具设置。直接使用 shell 命令 (nvm install 20、curl ... | sh、apt-get install) 同样有效，而且通常更简单。只有在你希望与 CI 配置完全一致，或者需要 setup-java 这类可处理多个发行版的 action 所带来的便利时，GitHub Actions 才更有用。

多个应用的本地 HTTPS 反向代理

通过 HTTPS 使用看起来像真实域名的主机名在后端运行多个服务，例如 app.example.com、api.example.com 和 admin.example.com。在 initialize 中安装一个反向代理，并将每个主机名路由到不同的本地上游端口。Caddy 可在一个工具中同时处理路由和本地 TLS。Caddyfile 会将每个主机名映射到一个上游，而 tls internal 会通过 Caddy 内置的 CA 为每个主机名自动签发受信任的证书。caddy trust 会将该 CA 根证书安装到系统信任存储中，再将同一个根证书添加到 NSS 数据库后，浏览器也会信任它。通过蓝图编辑器中的 文件附件 部分上传你的 Caddyfile；之后即可通过 $FILE_CADDYFILE 使用它。

Caddyfile

app.example.com {
  tls internal
  reverse_proxy 127.0.0.1:3000
}

api.example.com {
  tls internal
  reverse_proxy 127.0.0.1:3001
}

admin.example.com {
  tls internal
  reverse_proxy 127.0.0.1:3002
}

initialize:
  - name: Install Caddy and NSS tools
    run: |
      sudo apt-get install -y debian-keyring debian-archive-keyring \
        apt-transport-https curl libnss3-tools
      curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
        | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
      curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
        | sudo tee /etc/apt/sources.list.d/caddy-stable.list
      sudo apt-get update -qq
      sudo apt-get install -y caddy

  - name: Install Caddyfile, hosts entries, and trust internal CA
    run: |
      sudo install -m 0644 "$FILE_CADDYFILE" /etc/caddy/Caddyfile

      for host in app.example.com api.example.com admin.example.com; do
        grep -q " $host$" /etc/hosts \
          || echo "127.0.0.1 $host" | sudo tee -a /etc/hosts > /dev/null
      done

      sudo systemctl enable --now caddy
      sudo caddy trust

      mkdir -p ~/.pki/nssdb
      [ -f ~/.pki/nssdb/cert9.db ] \
        || certutil -d sql:$HOME/.pki/nssdb -N --empty-password

      CADDY_ROOT=/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt
      for _ in $(seq 1 30); do
        sudo test -f "$CADDY_ROOT" && break
        sleep 1
      done

      if sudo test -f "$CADDY_ROOT" \
         && ! certutil -d sql:$HOME/.pki/nssdb -L | grep -q "Caddy Local Authority"; then
        sudo install -o "$USER" -m 0644 "$CADDY_ROOT" /tmp/caddy-root.crt
        certutil -d sql:$HOME/.pki/nssdb -A -t "C,," \
          -n "Caddy Local Authority" -i /tmp/caddy-root.crt
        rm -f /tmp/caddy-root.crt
      fi

/etc/hosts 循环会让 app.example.com 在会话内解析到 127.0.0.1。你在 Caddyfile 中写入的每个 hostname，都要在其中添加一条记录。

要添加一个服务，请在 Caddyfile 中追加一个三行代码块，并在 /etc/hosts 循环中添加一条记录，然后通过 HTTPS 访问对应的 hostname。Caddy 会在首次请求时签发证书，因此无需为每个 app 单独生成证书。

全栈示例

这些示例展示了企业级和组织级配置如何组合使用。实际使用时，通常会按不同作用域拆分。这里将它们集中展示，供参考。

企业全栈（Artifactory）

一个完整的企业环境示例：企业 CA 证书、代理、Java (Maven)、Python (pip/uv)、Node.js (npm) 和 Docker，全部指向同一个 Artifactory 实例。

必需的 secrets

网络与信任 (账户级) ：

CORP_ROOT_CA_B64 — 经过 Base64 编码的企业 CA 证书
CORP_HTTP_PROXY — HTTP 代理 URL
CORP_HTTPS_PROXY — HTTPS 代理 URL
CORP_NO_PROXY — 不走代理的主机

注册表凭据 (组织级) ：

ARTIFACTORY_USER — Artifactory 用户名
ARTIFACTORY_TOKEN — Artifactory API 令牌或密码
ARTIFACTORY_MAVEN_URL — Maven 仓库 URL (例如，https://artifactory.example.com/artifactory/maven-virtual)
ARTIFACTORY_PYPI_URL — PyPI 仓库 URL (例如，https://user:token@artifactory.example.com/artifactory/api/pypi/pypi-virtual/simple)
ARTIFACTORY_NPM_URL — npm 仓库 URL (例如，https://artifactory.example.com/artifactory/api/npm/npm-virtual)
ARTIFACTORY_DOCKER_URL — Docker 注册表 URL (例如，artifactory.example.com)

这通常会拆分为三个作用域：

账户级 (initialize)： 证书与代理
组织级 (initialize)： 语言运行时安装
组织级 (maintenance)： 包含字面引用的注册表配置
会话命令： 显式提供 secrets、加载环境配置，并为单次 Docker 操作登录

此处合并显示以供参考：

initialize:
  # ── 账户级：网络与信任 ──────────────────────────────────────

  - name: Install corporate CA certificate
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      sudo update-ca-certificates
      echo 'export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt' \
        | sudo tee /etc/profile.d/node-ca.sh > /dev/null

  - name: Configure system-wide proxy
    run: |
      cat << 'PROXY' | sudo tee /etc/profile.d/proxy.sh > /dev/null
      export http_proxy="$CORP_HTTP_PROXY"
      export https_proxy="$CORP_HTTPS_PROXY"
      export no_proxy="$CORP_NO_PROXY"
      export HTTP_PROXY="$CORP_HTTP_PROXY"
      export HTTPS_PROXY="$CORP_HTTPS_PROXY"
      export NO_PROXY="$CORP_NO_PROXY"
      PROXY
      source /etc/profile.d/proxy.sh

  # ── Org-wide：语言运行时 ──────────────────────────────────────────

  - name: Install JDK 17 + Maven
    run: |
      set -o pipefail
      source /etc/profile.d/proxy.sh
      sudo --preserve-env=http_proxy,https_proxy,no_proxy,HTTP_PROXY,HTTPS_PROXY,NO_PROXY \
        apt-get update -qq
      sudo --preserve-env=http_proxy,https_proxy,no_proxy,HTTP_PROXY,HTTPS_PROXY,NO_PROXY \
        DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

      MAVEN_VERSION=3.9.9
      curl -fsSL "https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" \
        | sudo tar -xz -C /opt
      sudo ln -sf /opt/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/local/bin/mvn

  - name: Install uv
    run: |
      set -o pipefail
      source /etc/profile.d/proxy.sh
      curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance:
  # ── Org-wide：注册表配置 ───────────────────────────────────

  - name: Configure Maven → Artifactory
    run: |
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <mirrors>
          <mirror>
            <id>artifactory</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.ARTIFACTORY_MAVEN_URL}</url>
          </mirror>
        </mirrors>
        <servers>
          <server>
            <id>artifactory</id>
            <username>${env.ARTIFACTORY_USER}</username>
            <password>${env.ARTIFACTORY_TOKEN}</password>
          </server>
        </servers>
      </settings>
      EOF

  - name: Configure pip/uv → Artifactory PyPI
    run: |
      mkdir -p ~/.config
      cat > ~/.config/private-pypi.sh <<'EOF'
      export PIP_INDEX_URL="$ARTIFACTORY_PYPI_URL"
      export UV_INDEX_URL="$ARTIFACTORY_PYPI_URL"
      EOF

  - name: Configure npm → Artifactory
    run: |
      npm config set registry '${ARTIFACTORY_NPM_URL}'
      REGISTRY_HOST=$(echo "$ARTIFACTORY_NPM_URL" | sed 's|https\?://||;s|/.*||')
      npm config set "//${REGISTRY_HOST}/:_authToken" '${ARTIFACTORY_TOKEN}'

knowledge:
  - name: private_packages
    contents: |
      With the corresponding secrets available, source setup in each command:
        source /etc/profile.d/proxy.sh && mvn dependency:resolve
        source /etc/profile.d/proxy.sh && npm install
        source /etc/profile.d/proxy.sh && source ~/.config/private-pypi.sh && uv sync
  - name: private_container_images
    contents: |
      With the Artifactory and proxy secrets available, run in one shell.
      Replace team/image:tag with the image to pull:
        (
          set -euo pipefail
          umask 077
          source /etc/profile.d/proxy.sh
          DOCKER_CONFIG=$(mktemp -d)
          export DOCKER_CONFIG
          trap 'rm -rf "$DOCKER_CONFIG"' EXIT
          printf '%s' "$ARTIFACTORY_TOKEN" |
            docker login "$ARTIFACTORY_DOCKER_URL" \
              --username "$ARTIFACTORY_USER" --password-stdin
          docker pull "$ARTIFACTORY_DOCKER_URL/team/image:tag"
        )

在此示例中，所有仓库都指向同一个 Artifactory 实例，但 URL 路径不同。每种软件包生态系统都有各自的端点格式。即使是同一个仓库，Maven、PyPI、npm 和 Docker 的 URL 也各不相同。

多语言与不同制品库

当不同语言分别使用不同的私有仓库时 (例如，Maven 使用 Nexus，npm 使用 GitHub Packages，Python 使用 Artifactory) 。

必需的 secrets

NEXUS_MAVEN_URL — Nexus Maven 仓库 URL
NEXUS_USER — Nexus 用户名
NEXUS_PASS — Nexus 密码
GITHUB_PACKAGES_TOKEN — 具有 read:packages 作用域的 GitHub 个人访问令牌
ARTIFACTORY_USER — Artifactory 用户名
ARTIFACTORY_TOKEN — Artifactory API 令牌

通过 Git 集成连接你的 Git provider，并授予其访问托管这些 Go 模块的仓库的权限。

maintenance:
  # Maven → Nexus
  - name: Configure Maven → Nexus
    run: |
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <mirrors>
          <mirror>
            <id>nexus</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.NEXUS_MAVEN_URL}</url>
          </mirror>
        </mirrors>
        <servers>
          <server>
            <id>nexus</id>
            <username>${env.NEXUS_USER}</username>
            <password>${env.NEXUS_PASS}</password>
          </server>
        </servers>
      </settings>
      EOF

  # npm → GitHub Packages（作用域限定）
  - name: Configure npm → GitHub Packages
    run: |
      npm config set @myorg:registry https://npm.pkg.github.com
      npm config set //npm.pkg.github.com/:_authToken '${GITHUB_PACKAGES_TOKEN}'

  # Python → Artifactory
  - name: Configure pip → Artifactory
    run: |
      mkdir -p ~/.config
      cat > ~/.config/private-pypi.sh <<'EOF'
      export PIP_INDEX_URL="https://$ARTIFACTORY_USER:$ARTIFACTORY_TOKEN@artifactory.example.com/artifactory/api/pypi/pypi-virtual/simple"
      EOF

  # Go → 通过已连接的 Git provider 使用私有模块
  - name: Configure Go private modules
    run: |
      go env -w GOPRIVATE=github.com/myorg/*

knowledge:
  - name: private_python_packages
    contents: |
      With URL-encoded ARTIFACTORY_USER and ARTIFACTORY_TOKEN available, run:
        source ~/.config/private-pypi.sh && pip install -r requirements.txt

使用私有镜像源的气隙环境

在完全气隙环境中，Devin 无法访问任何公共 URL。所有工具、运行时和软件包都必须来自内部镜像源。

必需的 secrets

证书：

CORP_ROOT_CA_B64 — Base64 编码的企业 CA 证书

镜像访问：

APT_MIRROR_URL — 内部 Ubuntu APT 镜像 URL
MIRROR_USER — 用于镜像身份验证的用户名
MIRROR_PASS — 用于镜像身份验证的密码
JDK_TARBALL_URL — 从内部镜像下载 JDK tarball 的 URL
NODE_TARBALL_URL — 从内部镜像下载 Node.js tarball 的 URL

软件包注册表：

INTERNAL_MAVEN_URL — 内部 Maven 注册表 URL
INTERNAL_NPM_URL — 内部 npm 注册表 URL
INTERNAL_PYPI_URL — 内部 PyPI 注册表 URL

initialize:
  - name: Install corporate CA certificate
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      sudo update-ca-certificates

  - name: Replace apt sources with internal mirror
    run: |
      sudo sed -i "s|http://archive.ubuntu.com/ubuntu|$APT_MIRROR_URL|g" /etc/apt/sources.list
      sudo sed -i "s|http://security.ubuntu.com/ubuntu|$APT_MIRROR_URL|g" /etc/apt/sources.list
      sudo apt-get update -qq

  - name: Install JDK from internal mirror
    run: |
      # 从内部制品库下载 JDK 压缩包
      curl -fsSL -u "$MIRROR_USER:$MIRROR_PASS" "$JDK_TARBALL_URL" \
        | sudo tar -xz -C /usr/local
      sudo ln -sf /usr/local/jdk-17.*/bin/java /usr/local/bin/java
      sudo ln -sf /usr/local/jdk-17.*/bin/javac /usr/local/bin/javac
      echo "export JAVA_HOME=$(ls -d /usr/local/jdk-17.*)" \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install Node.js from internal mirror
    run: |
      curl -fsSL -u "$MIRROR_USER:$MIRROR_PASS" "$NODE_TARBALL_URL" \
        | sudo tar -xz -C /usr/local --strip-components=1

maintenance:
  - name: Configure all package managers for internal registry
    run: |
      # Maven
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <mirrors>
          <mirror>
            <id>internal</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.INTERNAL_MAVEN_URL}</url>
          </mirror>
        </mirrors>
        <servers>
          <server>
            <id>internal</id>
            <username>${env.MIRROR_USER}</username>
            <password>${env.MIRROR_PASS}</password>
          </server>
        </servers>
      </settings>
      EOF

      # npm
      npm config set registry '${INTERNAL_NPM_URL}'

      # pip
      mkdir -p ~/.config
      cat > ~/.config/private-pypi.sh <<'EOF'
      export PIP_INDEX_URL="$INTERNAL_PYPI_URL"
      EOF

knowledge:
  - name: internal_python_packages
    contents: |
      With INTERNAL_PYPI_URL available, run:
        source ~/.config/private-pypi.sh && pip install -r requirements.txt

在气隙环境中，Devin 所需的所有工具 (语言运行时、CLI 工具等) 都必须能从你的内部镜像源获取。公共软件仓库和下载站点均无法访问。

VPN + 证书 + 代理 + 编程语言

一个综合性的企业级配置示例，集成了 VPN 工具、证书、代理配置及多语言支持。该蓝图负责安装工具，并以字面引用的方式存储配置。在执行需要访问内部资源的操作时，请显式连接 VPN。

必需的 secrets

VPN：

VPN_CONFIG_B64 — Base64 编码的 OpenVPN 配置文件

网络与信任：

CORP_ROOT_CA_B64 — Base64 编码的企业 CA 证书
CORP_HTTP_PROXY — HTTP 代理 URL
CORP_HTTPS_PROXY — HTTPS 代理 URL
CORP_NO_PROXY — 无需通过代理的主机

注册表凭据：

MAVEN_REGISTRY_URL — Maven 注册表 URL
NPM_REGISTRY_URL — npm 注册表 URL
PYPI_REGISTRY_HOST — PyPI 注册表主机名
REGISTRY_USER — 注册表用户名 (用于 Maven 和 pip)
REGISTRY_PASS — 注册表密码 (用于 Maven 和 pip)
REGISTRY_TOKEN — npm 身份验证令牌

initialize:
  # 1. VPN 客户端
  - name: Install VPN client
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openvpn

  # 2. DNS — 解析内部主机名
  - name: Configure DNS
    run: |
      sudo mkdir -p /etc/systemd/resolved.conf.d
      cat << 'DNS' | sudo tee /etc/systemd/resolved.conf.d/corp.conf > /dev/null
      [Resolve]
      DNS=10.0.0.53
      Domains=corp.internal
      DNS
      sudo systemctl restart systemd-resolved || true

  # 3. 证书 — 信任内部 CA
  - name: Install CA certificate
    run: |
      set -o pipefail
      printf '%s' "$CORP_ROOT_CA_B64" | base64 -d | openssl x509 -outform PEM \
        | sudo tee /usr/local/share/ca-certificates/corp-root-ca.crt > /dev/null
      sudo update-ca-certificates
      echo 'export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt' \
        | sudo tee /etc/profile.d/node-ca.sh > /dev/null

  # 4. 代理 — 通过企业代理路由流量
  - name: Configure proxy
    run: |
      cat << 'PROXY' | sudo tee /etc/profile.d/proxy.sh > /dev/null
      export http_proxy="$CORP_HTTP_PROXY"
      export https_proxy="$CORP_HTTPS_PROXY"
      export no_proxy="$CORP_NO_PROXY"
      export HTTP_PROXY="$CORP_HTTP_PROXY"
      export HTTPS_PROXY="$CORP_HTTPS_PROXY"
      export NO_PROXY="$CORP_NO_PROXY"
      PROXY
      source /etc/profile.d/proxy.sh

  # 5. 语言运行时
  - name: Install language runtimes over VPN
    run: |
      (
        set -euo pipefail
        umask 077
        VPN_DIR=$(mktemp -d)
        cleanup() {
          if [ -f "$VPN_DIR/openvpn.pid" ]; then
            sudo kill "$(cat "$VPN_DIR/openvpn.pid")" || true
          fi
          sudo rm -rf "$VPN_DIR"
        }
        trap cleanup EXIT
        printf '%s' "$VPN_CONFIG_B64" | base64 -d > "$VPN_DIR/corp.conf"
        sudo openvpn --config "$VPN_DIR/corp.conf" \
          --writepid "$VPN_DIR/openvpn.pid" --daemon
        for i in $(seq 1 30); do
          if ip link show tun0 >/dev/null 2>&1; then break; fi
          sleep 1
        done
        ip link show tun0 >/dev/null
        source /etc/profile.d/proxy.sh
        sudo --preserve-env=http_proxy,https_proxy,no_proxy,HTTP_PROXY,HTTPS_PROXY,NO_PROXY \
          apt-get update -qq
        sudo --preserve-env=http_proxy,https_proxy,no_proxy,HTTP_PROXY,HTTPS_PROXY,NO_PROXY \
          DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
        echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
          | sudo tee /etc/profile.d/java.sh > /dev/null
        npm install -g pnpm
        curl -LsSf https://astral.sh/uv/install.sh | sh
      )

maintenance:
  - name: Configure Maven
    run: |
      mkdir -p ~/.m2
      cat > ~/.m2/settings.xml <<'EOF'
      <settings>
        <mirrors>
          <mirror>
            <id>corp</id>
            <mirrorOf>*</mirrorOf>
            <url>${env.MAVEN_REGISTRY_URL}</url>
          </mirror>
        </mirrors>
        <servers>
          <server>
            <id>corp</id>
            <username>${env.REGISTRY_USER}</username>
            <password>${env.REGISTRY_PASS}</password>
          </server>
        </servers>
      </settings>
      EOF

  - name: Configure npm
    run: |
      npm config set registry '${NPM_REGISTRY_URL}'
      NPM_HOST=$(echo "$NPM_REGISTRY_URL" | sed 's|https\?://||;s|/.*||')
      npm config set "//${NPM_HOST}/:_authToken" '${REGISTRY_TOKEN}'

  - name: Configure pip/uv
    run: |
      mkdir -p ~/.config
      cat > ~/.config/private-pypi.sh <<'EOF'
      export PIP_INDEX_URL="https://$REGISTRY_USER:$REGISTRY_PASS@${PYPI_REGISTRY_HOST}/simple"
      export UV_INDEX_URL="$PIP_INDEX_URL"
      EOF

knowledge:
  - name: internal_packages
    contents: |
      Use the temporary OpenVPN setup/cleanup block from the template library
      when an operation needs VPN access. Inside that block, with the registry
      and proxy secrets available, replace the sample curl command with:
        source /etc/profile.d/proxy.sh
        mvn dependency:resolve
        npm install
        source ~/.config/private-pypi.sh
        uv sync
      Percent-encode the pip URL credentials. Disconnect the VPN and remove its
      temporary files when the operation finishes.

需要具备引导访问能力。 在建立隧道之前，必须已预装 OpenVPN 客户端或能够进行安装。VPN_CONFIG_B64 必须包含内联的证书/密钥，使用 dev tun0，并且无需交互式身份验证即可连接。运行时下载在同一个隧道生命周期内完成，并显式加载代理环境。会话操作请重复网络与连通性中的 VPN 设置/清理块；蓝图不会在会话开始时重新连接 VPN。

编写优质蓝图的技巧

先在会话中测试命令。 在将命令添加到蓝图之前，先在 Devin 会话中手动运行一遍。这样比等待完整构建周期更快。
一次性安装的工具用 initialize，依赖项用 maintenance。 任何安装需要几分钟的内容 (编译器、大型二进制文件、全局工具) 都应放在 initialize 中。较快的依赖命令 (npm install、uv sync) 则应放在 maintenance 中。
让 maintenance 命令保持快速。 尽量控制在 2 分钟以内。这些命令会在构建期间运行，并在会话开始时提供给 Agent。
非敏感的环境变量请使用 $ENVRC。 不要将凭据或派生令牌写入 $ENVRC、.bashrc 或 .profile。请在需要它的命令中显式 source 依赖 secrets 的 shell 设置。
给步骤命名。 使用带有 name 字段的展开形式后，构建日志中的失败会更容易定位。
monorepo 请使用 subshell。 (cd packages/foo && npm install) 会在 subshell 中运行，因此后续步骤不会受目录变更影响。
使用 npm install，不要使用 npm ci。 npm ci 会删除 node_modules 并从头重新安装，这对 maintenance 来说太慢。
敏感信息请使用代码仓库 secrets。 请在仓库蓝图编辑器的 Secrets 选项卡中进行配置，而不要将其硬编码到蓝图中。

有关语法细节，请参阅蓝图参考。有关构建失败的故障排除，请参阅声明式配置 > 故障排除。

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Release Notes

Devin 蓝图模板库

快速开始

仓库蓝图

Python

Node.js

Go

Java

Ruby on Rails

Rust

Monorepo

私有包注册表

Node.js 注册表

Python 软件包注册表

JVM 软件包注册表

其他软件包注册表

企业基础架构

网络与连接

身份与安全

系统配置

高级用法

全栈示例

编写优质蓝图的技巧

​快速开始

​仓库蓝图

​Python

​Node.js

​Go

​Java

​Ruby on Rails

​Rust

​Monorepo

​私有包注册表

​Node.js 注册表

​Python 软件包注册表

​JVM 软件包注册表

​其他软件包注册表

​企业基础架构

​网络与连接

​身份与安全

​系统配置

​高级用法

​全栈示例

​编写优质蓝图的技巧

快速开始

仓库蓝图

Python

Node.js

Go

Java

Ruby on Rails

Rust

Monorepo

私有包注册表

Node.js 注册表

Python 软件包注册表

JVM 软件包注册表

其他软件包注册表

企业基础架构

网络与连接

身份与安全

系统配置

高级用法

全栈示例

编写优质蓝图的技巧