setup-devcontainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Devcontainer Setup

Devcontainer 配置搭建

Generate devcontainer configuration for any repository. Optionally create a Gitpod/Ona project and verify with a test environment.

为任意代码仓库生成devcontainer配置。可选择创建Gitpod/Ona项目并通过测试环境验证。

When to Use

适用场景

First-time devcontainer setup for a repo
Migrating from legacy
```
.gitpod.yml
```
Re-generating config after major stack changes
Verifying an existing devcontainer setup works

为代码仓库首次搭建devcontainer环境
从旧版
```
.gitpod.yml
```
迁移配置
技术栈重大变更后重新生成配置
验证现有devcontainer配置是否可用

Phase 1: Config Generation

第一阶段：配置生成

1.1 Detect Framework

1.1 检测技术框架

Scan the repo directly (no prerequisite files required):

```
Gemfile
```
/
```
config/routes.rb
```
→ Rails
```
package.json
```
with
```
next
```
→ Next.js
```
package.json
```
with
```
strapi
```
→ Strapi
```
manage.py
```
/
```
settings.py
```
→ Django
```
composer.json
```
with
```
laravel
```
→ Laravel
```
composer.json
```
with
```
symfony
```
→ Symfony
```
package.json
```
with
```
express
```
→ Express
```
package.json
```
with
```
@nestjs
```
→ NestJS
Multiple
```
package.json
```
in subdirs → Monorepo

Also detect:

Database: PostgreSQL, MySQL, MongoDB, SQLite (from config files, Gemfile, package.json)

Default branch:

git symbolic-ref refs/remotes/origin/HEAD

or check

main

master

CLAUDE.md: If missing, suggest running
```
setup-harness
```
but do NOT block
Speckit:
```
.specify/
```
directory exists → note speckit commands available
Legacy config:
```
.gitpod.yml
```
exists → extract ports, tasks, extensions as migration hints

直接扫描代码仓库（无需前置文件）：

```
Gemfile
```
/
```
config/routes.rb
```
→ Rails
包含
```
next
```
的
```
package.json
```
→ Next.js
包含
```
strapi
```
的
```
package.json
```
→ Strapi
```
manage.py
```
/
```
settings.py
```
→ Django
包含
```
laravel
```
的
```
composer.json
```
→ Laravel
包含
```
symfony
```
的
```
composer.json
```
→ Symfony
包含
```
express
```
的
```
package.json
```
→ Express
包含
```
@nestjs
```
的
```
package.json
```
→ NestJS
子目录中存在多个
```
package.json
```
→ 单仓库多项目（Monorepo）

同时检测：

数据库：PostgreSQL、MySQL、MongoDB、SQLite（从配置文件、Gemfile、package.json中识别）

默认分支：通过

git symbolic-ref refs/remotes/origin/HEAD

获取，或检查

main

master

分支

CLAUDE.md：若缺失，建议运行
```
setup-harness
```
但不强制要求
Speckit：存在
```
.specify/
```
目录 → 记录可用的speckit命令
旧版配置：存在
```
.gitpod.yml
```
→ 提取端口、任务、扩展作为迁移参考

1.2 Ask User

1.2 询问用户

Confirm detected stack, then ask:

Optional tasks: Fly.io CLI, database backup/restore from S3
Additional VS Code extensions
Custom port overrides
Preserve existing
```
.devcontainer/
```
or
```
.ona/
```
files?

确认检测到的技术栈后，询问以下内容：

可选任务：Fly.io CLI、从S3备份/恢复数据库
额外的VS Code扩展
自定义端口覆盖
是否保留现有的
```
.devcontainer/
```
或
```
.ona/
```
文件？

1.3 Generate Files

1.3 生成文件

.devcontainer/Dockerfile
— Generic base + detected DB packages
.devcontainer/devcontainer.json
— Features, extensions, ports
.ona/automations.yaml
(if using Gitpod/Ona) — Services + tasks:
- Standard tasks:
```
setup_node
```
  ,
```
setup_git_config
```
  ,
```
setup_gnupg
```
  ,
```
setup_ssh
```
  ,
```
setup_aws
```
- install_claude_code
  —
```
curl -fsSL https://claude.ai/install.sh | sh
```
  (always included)
- Framework-specific services and dependency install tasks
- Optional tasks based on user choices

.devcontainer/Dockerfile
— 通用基础镜像 + 检测到的数据库依赖包
.devcontainer/devcontainer.json
— 功能特性、扩展、端口配置
.ona/automations.yaml
（若使用Gitpod/Ona） — 服务 + 任务：
- 标准任务：
```
setup_node
```
  、
```
setup_git_config
```
  、
```
setup_gnupg
```
  、
```
setup_ssh
```
  、
```
setup_aws
```
- install_claude_code
  —
```
curl -fsSL https://claude.ai/install.sh | sh
```
  （默认包含）
- 框架专属服务和依赖安装任务
- 根据用户选择添加可选任务

1.4 Validate

1.4 验证配置

No placeholder values remain (
```
[dbname]
```
,
```
[backend-dir]
```
, etc.)
Ports match detected frameworks
Extensions match detected frameworks
DB service configured if needed

无占位符残留（如
```
[dbname]
```
、
```
[backend-dir]
```
等）
端口配置与检测到的框架匹配
扩展配置与检测到的框架匹配
数据库服务已按需配置

Phase 2: Gitpod/Ona Project Setup (optional)

第二阶段：Gitpod/Ona项目配置（可选）

Skip this phase if not using Gitpod/Ona.

若不使用Gitpod/Ona可跳过此阶段。

2.1 Prerequisites

2.1 前置检查

bash

gitpod version && gitpod whoami

If not authenticated, user needs

gitpod login --token "<PAT>" --non-interactive

bash

gitpod version && gitpod whoami

若未认证，用户需执行

gitpod login --token "<PAT>" --non-interactive

。

2.2 Check Existing Project

2.2 检查现有项目

bash

gitpod project list --timeout 30s

Search output for the repo URL. If project exists, skip to 2.4.

bash

gitpod project list --timeout 30s

在输出中搜索仓库URL。若项目已存在，直接跳至2.4步骤。

2.3 Create Project

2.3 创建项目

bash

REPO_URL=$(git remote get-url origin)
gitpod project create "$REPO_URL" --timeout 30s

Extract the project ID from output.

bash

REPO_URL=$(git remote get-url origin)
gitpod project create "$REPO_URL" --timeout 30s

从输出中提取项目ID。

2.4 Configure Secrets

2.4 配置密钥

Gitpod has two secret scopes. Both are needed for a fully functional environment.

Gitpod有两种密钥作用域，两者均需配置才能实现完整功能的环境。

Project secrets (per-project, set via CLI)

项目级密钥（按项目配置，通过CLI设置）

Check existing:

bash

gitpod project secret list <project-id> -o json --timeout 15s

Required project secrets:

```
CLAUDE_CODE_OAUTH_TOKEN
```
— Claude Code authentication
```
GH_TOKEN
```
— GitHub API access (for
```
gh
```
CLI inside pods)
Project-specific secrets (
```
ENV_PASS
```
,
```
AWS_*
```
, etc.)

Set missing ones:

bash

gitpod project secret set <project-id> CLAUDE_CODE_OAUTH_TOKEN "<token>"
gitpod project secret set <project-id> GH_TOKEN "<token>"

Never handle token values directly — user provides them.

检查现有密钥：

bash

gitpod project secret list <project-id> -o json --timeout 15s

必填项目级密钥：

```
CLAUDE_CODE_OAUTH_TOKEN
```
— Claude Code认证令牌
```
GH_TOKEN
```
— GitHub API访问令牌（用于容器内的
```
gh
```
CLI）
项目专属密钥（如
```
ENV_PASS
```
、
```
AWS_*
```
等）

设置缺失的密钥：

bash

gitpod project secret set <project-id> CLAUDE_CODE_OAUTH_TOKEN "<token>"
gitpod project secret set <project-id> GH_TOKEN "<token>"

切勿直接处理令牌值 — 需由用户提供。

Personal secrets (user-level, set via dashboard)

个人级密钥（用户级配置，通过控制台设置）

Set once per account, apply to ALL environments. Configured in the web dashboard under user settings, NOT via CLI.

Required personal secrets:

```
GITCONFIG
```
— base64-encoded
```
~/.gitconfig
```
```
GPG_1
```
through
```
GPG_5
```
— base64-encoded GPG keyring tar.gz split into 5 chunks
```
SSH_PRIVATE_KEY
```
— base64-encoded SSH private key
```
SSH_PUBLIC_KEY
```
— base64-encoded SSH public key
```
SSH_KNOWN_HOSTS
```
— base64-encoded known_hosts

每个账户只需配置一次，适用于所有环境。需在Web控制台的用户设置中配置，无法通过CLI设置。

必填个人级密钥：

```
GITCONFIG
```
— base64编码的
```
~/.gitconfig
```
文件
```
GPG_1
```
至
```
GPG_5
```
— base64编码的GPG密钥环tar.gz分块文件（共5块）
```
SSH_PRIVATE_KEY
```
— base64编码的SSH私钥
```
SSH_PUBLIC_KEY
```
— base64编码的SSH公钥
```
SSH_KNOWN_HOSTS
```
— base64编码的known_hosts文件

2.5 Output

2.5 输出结果

Report:

Project ID
Repo URL
Pool naming convention:
```
{project}-{purpose}-runner-{n}
```
Configured secrets

报告以下内容：

项目ID
仓库URL
资源池命名规则：
```
{project}-{purpose}-runner-{n}
```
已配置的密钥

Phase 3: Test Environment (optional)

第三阶段：测试环境验证（可选）

3.1 Create Test Env

3.1 创建测试环境

bash

gitpod environment create <project-id> \
  --name "<project>-setup-test" \
  --class-id 0198bec9-2af2-704f-a4f9-927101d8b844 \
  --set-as-context --dont-wait

bash

gitpod environment create <project-id> \
  --name "<project>-setup-test" \
  --class-id 0198bec9-2af2-704f-a4f9-927101d8b844 \
  --set-as-context --dont-wait

3.2 Poll Until Running

3.2 轮询直至环境运行

Every 10s, timeout 3min:

bash

gitpod environment get <env-id> --timeout 15s

每10秒轮询一次，超时时间3分钟：

bash

gitpod environment get <env-id> --timeout 15s

3.3 Verify Checklist

3.3 验证清单

SSH in and run checks:

bash

gitpod environment ssh <env-id> -- "<command>"

Claude Code installed:
```
claude --version
```

Git identity configured:

git config --global user.name && git config --global user.email

No repo-level git overrides:
```
git config --local user.name
```
should return empty/error
Git clean on default branch:
```
git status --porcelain
```
is empty
Services running: DB responds (
```
pg_isready
```
or
```
mysqladmin ping
```
)
App server starts: framework start command runs without immediate crash
Speckit available:
```
ls .specify/
```
if detected in Phase 1

通过SSH连接并执行检查：

bash

gitpod environment ssh <env-id> -- "<command>"

Claude Code已安装：
```
claude --version
```

Git身份已配置：

git config --global user.name && git config --global user.email

无仓库级Git配置覆盖：
```
git config --local user.name
```
应返回空值或错误
默认分支Git状态干净：
```
git status --porcelain
```
输出为空
服务已运行：数据库可响应（
```
pg_isready
```
或
```
mysqladmin ping
```
）
应用服务器可启动：框架启动命令可正常运行无立即崩溃
Speckit可用：若第一阶段检测到则执行
```
ls .specify/
```

3.4 Teardown

3.4 销毁测试环境

bash

gitpod environment stop <env-id>
gitpod environment delete <env-id>

If user passes

--keep-open

, only report the env ID and SSH command.

bash

gitpod environment stop <env-id>
gitpod environment delete <env-id>

若用户传入

--keep-open

参数，仅返回环境ID和SSH命令即可。

Environment Classes

实例规格列表

Class	ID	Specs
Small	0198bec9-2af2-7056-b500-a1145383a73c	2 vCPU / 8 GiB
Regular	0198bec9-2af2-704f-a4f9-927101d8b844	4 vCPU / 16 GiB
Large	0198bec9-2af2-7049-a4db-caaca7016e9f	8 vCPU / 32 GiB

实例规格	ID	配置参数
小型	0198bec9-2af2-7056-b500-a1145383a73c	2 vCPU / 8 GiB
常规	0198bec9-2af2-704f-a4f9-927101d8b844	4 vCPU / 16 GiB
大型	0198bec9-2af2-7049-a4db-caaca7016e9f	8 vCPU / 32 GiB

Key Rules

核心规则

Never hardcode secrets — tokens go in project secrets

Claude Code install: always use

curl -fsSL https://claude.ai/install.sh | sh

(NOT npm)

Default to Regular class unless user specifies otherwise
Always tear down test envs unless
```
--keep-open
```

SSH pattern:

gitpod environment ssh <env-id> -- "<command>"

This skill sets up projects, not orchestration — dispatch and scheduling are handled separately

切勿硬编码密钥 — 令牌需存储在项目级密钥中
Claude Code安装：始终使用
```
curl -fsSL https://claude.ai/install.sh | sh
```
（禁止使用npm）
默认使用常规规格：除非用户明确指定其他规格
默认销毁测试环境：除非传入
```
--keep-open
```
参数

SSH命令格式：

gitpod environment ssh <env-id> -- "<command>"

本技能仅负责项目搭建：调度和编排功能由其他模块单独处理