Menyiapkan lingkungan
Lingkungan adalah stack berjalan milik satu space: layanan yang dibutuhkan sebuah branch, terisolasi dari semua space lain, terlihat di bilah sisi, dan dapat dijangkau agen. Pull request juga mendapatkannya, karena PR sudah memiliki space sendiri.
Admin ruang kerja menulis definisi satu kali. Anggota lalu menekan Mulai di bagian Lingkungan pada bilah sisi space atau PR. Definisi disimpan di basis data ruang kerja, sehingga branch fitur tidak pernah mengubah apa yang dijalankan Control Center, meskipun alat tetap menjalankan kode branch tersebut.
Membuat definisi
Bagian berjudul “Membuat definisi”- Buka Pengaturan → Ruang kerja → Lingkungan. Hanya admin ruang kerja yang dapat mengubah definisi, dan hanya pemilik server yang dapat menyimpan definisi yang berjalan di host server (lihat Siapa yang dapat menyimpan apa).
- Klik Definisi baru, lalu Definisi kosong atau Draf dari repo. Draf memindai repo untuk file compose,
Procfile, dan skrippackage.json, lalu Anda meninjau hasilnya. - Isi formulir, atau gunakan tab JSON. Contoh di halaman ini adalah JSON tersebut.
- Klik Jalankan pengujian. Ini memulai lingkungan sekali pakai, menunggu sampai siap, lalu menghancurkannya.
Saat menyimpan, definisi diperiksa dengan ketat. Field yang tidak dikenal, nilai dengan tipe yang salah, atau pilihan yang salah eja ditolak, beserta path-nya dan nama valid terdekat, misalnya repos.app.requird: Unknown field. Did you mean "required"?. $schema di tingkat teratas diizinkan.
Untuk menyimpan definisi di repo, gunakan Tautkan file repo. Control Center membaca file hanya dari branch default dan hanya menjalankan versi yang disetujui: oleh admin ruang kerja, atau oleh pemilik server ketika definisi berjalan di host. Versi yang lebih baru menampilkan Pembaruan tersedia dan tidak mengubah apa pun sampai disetujui.
Siapa yang dapat menyimpan apa
Bagian berjudul “Siapa yang dapat menyimpan apa”Sebuah definisi lingkungan dapat menjalankan perintah di host server sebagai pengguna server itu sendiri. Itu keputusan pemilik server, bukan peran ruang kerja:
- Sebuah definisi berjalan di host ketika ia memiliki penempatan host, pemeriksaan yang menjalankan perintah, atau tugas
provisionatauarchive. Tugas-tugas itu berjalan di worktree space di host, apa pun penempatannya. - Hanya pemilik server yang dapat menyimpan atau menyetujui definisi yang berjalan di host. Itu termasuk menyetujui versi baru dari file repo yang ditautkan. Admin ruang kerja yang mencobanya melihat “Hanya pemilik server yang dapat menyimpan atau menyetujui lingkungan yang berjalan di host server. Admin ruang kerja dapat menggunakan lingkungan yang berjalan di rig.”
- Admin ruang kerja dapat menyimpan dan menyetujui definisi yang sepenuhnya berjalan di rig:
"placement": "rig", tanpa perintah pemeriksaan dan tanpa tugasprovisionatauarchive. - Anggota memulai, menghentikan, dan menggunakan lingkungan dalam kedua kasus.
- Definisi yang berjalan di host hanya berjalan setelah pemilik server saat ini menyimpan atau menyetujuinya. Server mencatat persetujuan itu sendiri dan memeriksanya sebelum setiap mulai, pemeriksaan, tugas, dan sinkronisasi kepala pull request. Definisi yang belum disetujui pemilik saat ini, seperti yang disimpan oleh pemilik sebelumnya, menunggu di bawah barisnya dalam daftar lingkungan dan di editor. Pemilik server melihat “Berjalan di server ini. Setujui agar bisa dimulai.” dengan Setujui, yang menyimpannya tanpa perubahan; semua orang lain melihat “Berjalan di server ini. Pemilik server harus menyetujuinya sebelum bisa dimulai.”
- Lingkungan yang ditahan untuk persetujuan itu menyatakan “Pemilik server belum menyetujui lingkungan ini, sehingga tidak dapat berjalan di server ini.” Pemilik server justru melihat “Anda belum menyetujui lingkungan ini. Lingkungan ini berjalan di server ini, jadi akan dimulai setelah Anda menyetujui definisinya.” dengan Tinjau dan setujui, yang membuka definisinya.
- Terminal proses lingkungan, dan terminal yang dibuka saat mulai ketika ia membutuhkan Anda, berjalan di host server. Mengetik di salah satunya, mengubah ukurannya, atau menutupnya memerlukan akses tulis ke setiap repositori yang diekspos space, yang dapat dibaca melalui proses masuk forge Anda sendiri: sama seperti memulai lingkungan. Orang lain tidak dapat menjangkau terminal tersebut sama sekali.
Definisi terkecil
Bagian berjudul “Definisi terkecil”Repo compose sederhana hanya membutuhkan ini:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Semua hal lain memiliki nilai default: file compose ditemukan, setiap layanan berjalan, port ditetapkan, endpoint HTTP dideteksi, dan lingkungan diberi nama sesuai branch.
Jenis komponen
Bagian berjudul “Jenis komponen”Lingkungan adalah daftar komponen berurutan. Masing-masing menunggu komponen sebelumnya siap, kecuali after menyebut yang lain, dan penghentian berjalan terbalik. enabledWhen membuat komponen bergantung pada opsi atau peran, misalnya opt.seed, !opt.seed, atau repo.web. Komponen yang perannya opsional dan tidak ada di space dikecualikan dengan cara yang sama, tanpa perlu enabledWhen: komponen itu tidak dimulai dan tidak memiliki {port.*} atau {url.*}, sehingga komponen lain yang membacanya gagal saat memulai.
| Jenis | Siapa yang menjalankan | Kegunaan |
|---|---|---|
compose |
Driver compose Control Center | File compose apa pun, satu per lingkungan |
cli |
Alat Anda. Control Center memanggil kata kerja yang dipetakan dan membaca JSON | Alat yang memiliki siklus hidup, domain, dan datanya sendiri |
process |
Control Center, dalam sesi terminal yang diawasi | Server dev dan worker |
task |
Control Center, sekali per pemicu | Instalasi, migrasi, pengujian |
app |
Control Center, saat seseorang mengklik Luncurkan | Aplikasi desktop |
Komponen task menerima daftar when:
| Pemicu | Berjalan |
|---|---|
provision |
Saat worktree dibuat (lihat tugas worktree di bawah) |
create |
Sekali per lingkungan, dan lagi setelah reset |
start |
Pada setiap mulai |
change |
Setelah sinkronisasi, saat jalur yang berubah cocok dengan onChange |
manual |
Atas permintaan: Jalankan, cc-env run <id>, atau environment_run_task |
archive |
Tepat sebelum worktree dihancurkan |
Tugas yang tidak punya pekerjaan saat proses mulai menampilkan status Menganggur dan tidak masuk daftar langkah yang ditampilkan saat lingkungan dimulai: tugas manual atau change, atau tugas create yang sudah pernah dijalankan.
Perintah yang diberikan sebagai array adalah argv, sehingga nilai opsi tidak pernah melewati shell. String, atau script dengan array baris, berjalan di bawah bash -lc. Placeholder seperti {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>}, dan {url.<role>} hanya diperluas di argv. Perintah shell membaca nilai yang sama sebagai variabel CC_ENV_*, misalnya $CC_ENV_PORT_WEB. Placeholder yang tidak dikenal di komponen yang ikut serta menghentikan proses mulai sebelum ada yang dijalankan.
Setiap perintah dan terminal space juga mendapatkan CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>, dan, di space PR, CC_PR_NUMBER serta CC_PR_IS_FORK. Dengan komponen compose, mereka juga mendapatkan COMPOSE_PROJECT_NAME dan COMPOSE_FILE, sehingga docker compose exec dalam tugas mencapai proyek yang benar.
Peran dan direktori kerja
Bagian berjudul “Peran dan direktori kerja”Definisi mengikat peran ke repo ruang kerja, sehingga satu stack dapat mencakup beberapa repo:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: space dapat memulai lingkungan jika memiliki setidaknya satu peran jangkar. Jika dua definisi cocok, orang yang memulai memilih.required: stack tidak dapat berjalan tanpa repo ini.whenMissing: yang terjadi saat space tidak memiliki peran tersebut.addToSpacemenambahkan repo pada branch default-nya dan merupakan default untuk peranrequired.useSourcemeneruskan checkout terdaftar Anda, yang harus diperlakukan hanya baca.skipmembiarkan variabel tidak disetel dan merupakan default lainnya.- Memulai memerlukan izin
writepada repo jangkar di space dan akses baca ke setiap repo terikat lainnya.
Perintah berjalan di peran pertama yang dideklarasikan dalam repos, tidak pernah di peran lain yang kebetulan dimiliki space, sehingga definisi satu repo tidak pernah menyebutkannya. Komponen apa pun dapat menggantinya dengan "cwd": { "role": "e2e", "path": "packages/ui" }. Kedua bidang bersifat opsional. Ketika peran pertama mungkin tidak ada di sebuah space, karena peran itu bukan required dan bukan satu-satunya anchor, setiap komponen harus menyebut perannya.
Port dan URL
Bagian berjudul “Port dan URL”Control Center menetapkan port host sebelum apa pun dimulai, dari rentang yang berlaku untuk seluruh host (42000 sampai 49999 secara default, dalam blok berisi 32). Port tetap sama selama lingkungan hidup, dan port compose hanya terikat ke 127.0.0.1.
- Port compose tidak perlu dideklarasikan. Baca sebagai
{port.postgres.5432}atauCC_ENV_PORT_POSTGRES_5432. - Port lain dideklarasikan di tempat penggunaannya, dengan
"port": "web"atau"ports": ["web", "hmr"], dan dibaca sebagai{port.web}. Proses dengan port juga mendapatkanPORTdanHOST=127.0.0.1.
Endpoint HTTP mendapatkan URL di router server, yang mendengarkan pada satu port loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>adalah branch sebagai slug, ataupr-<n>di space PR.<project>adalahnaming.project, atau nama definisi jika tidak ada.- Nama
*.localhostmengarah ke loopback, sehingga tidak memerlukan entri hosts atau DNS, dan nama host memisahkan cookie antar lingkungan. - Port compose yang menjawab HTTP terdeteksi, dan
httppada komponen menggantikan tebakan itu. Proses memerlukan"endpoint": { "role": "web", "primary": true }, yang juga menyediakan{url.web}. - Di browser (VM), gunakan Buka di Browser (VM).
https://web--fix-login--shop.localhost/mencapai rute yang sama di sana. - Seluruh label tetap dalam 63 karakter, sehingga nama panjang dipendekkan dengan hash.
- Dua endpoint tidak berbagi domain induk. Aplikasi yang membutuhkan satu cookie di keduanya harus menyajikannya dari satu endpoint.
Untuk URL yang harus didaftarkan terlebih dahulu, seperti pengalihan OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } memberikan sekumpulan nama tetap.
policy menentukan kapan lingkungan berjalan. autoCreate bernilai off, prSpaces, atau allSpaces, idleStopMinutes default-nya 240, followPrHead menyinkronkan lingkungan PR saat head-nya bergerak, dan dengan maxRunning (default 6) Mulai menawarkan untuk menghentikan lingkungan yang paling lama tidak digunakan.
Contoh: aplikasi compose
Bagian berjudul “Contoh: aplikasi compose”Aplikasi web dan Postgres dari satu file compose, dengan .env yang diabaikan git, migrasi, dan tugas pengujian. seedFiles menyalin file bernama dari checkout terdaftar Anda ke setiap worktree baru.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks memungkinkan layanan tanpa pemeriksaan kesehatan sendiri menahan komponen berikutnya. Tanpanya, kontainer yang berjalan dianggap siap, dan migrasi bisa mendahului basis data yang masih memulai.
Setiap mulai dan refresh menjalankan up dengan --remove-orphans, sehingga layanan yang dihapus dari file compose berhenti dan membebaskan port-nya. Image dibangun saat mulai dan saat refresh, kecuali komponen menetapkan "build": false.
Contoh: CLI kustom
Bagian berjudul “Contoh: CLI kustom”Alat rekaan acme yang memiliki kontainer, domain, dan TLS-nya sendiri. Control Center memberikan {name} dan mengetahui sisanya dari status. Control Center tidak pernah menurunkan nama host alat dan tidak pernah mengedit /etc/hosts.
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create,status, dandestroywajib ada. Control Center memilihcreateataustartdari status yang dibacanya. Kata kerja apa pun boleh berupa{ "shell": "…" }alih-alih argv.interactivemenyebutkan kata kerja, daricreate,start, danreset, yang dapat meminta apa yang dibutuhkan di terminal. Ketika kata kerja seperti itu keluar dengan kode 3 untuk orang yang menekan Mulai, Control Center menjalankan ulang kata kerja yang sama di tab terminal, dan proses mulai berlanjut setelah kata kerja itu keluar dengan kode 0. Di sana kondisiinteractivebernilai benar danCC_ENV_INTERACTIVE=1diatur, sehingga{ "if": "!interactive", "args": ["--json"] }mempertahankan output mesin untuk pipe. Mulai oleh agen, atau mulai otomatis, tidak pernah membuka terminal: lingkungan menampilkan Perlu tindakan dan menunggu.destroyyang gagal tetap menghapus lingkungan jikastatuskemudian melaporkanmissing, sehingga lingkungan yang sudah tidak dimiliki alat selalu bisa dihapus.listmemungkinkan Control Center menyadari lingkungan yang telah hilang dari alat. Lingkungan hanya ditandai hilang ketika namanya tidak ada dilistdanstatuskemudian menyatakanmissing. Output yang tidak dapat dibaca sebagai daftar tidak mengubah apa pun.{service}dilogsdanexecharus berupa satu kata yang tidak diawali-, dan salah satu layanan yang dilaporkan alat terakhir kali, jika alat pernah melaporkan layanan.statusMapmembaca JSON alat dengan penunjuk JSON, dengan*cocok dengan setiap item. Aturan status berurutan dan kecocokan pertama menang. Kondisi berupapathdenganequals, atauanymaupunnonedenganwhere.keepsDataOnStop: falsemematikan penghentian saat diam dan menambahkan peringatan kehilangan data ke Berhenti. Setel ini jika penghentian menghilangkan data.routing.mode: "tool"menghubungkan nama host alat ke browser (VM) dan agen. Domain harus berakhir dengan.test,.localhost, atau.internal, dan URL yang dilaporkan di luarnya dibuang.
Alat milik Anda dapat melewati statusMap dan mencetak kontrak status yang dijelaskan di akhir halaman ini.
Contoh: monorepo pnpm
Bagian berjudul “Contoh: monorepo pnpm”Hanya proses dan tugas, tanpa kontainer. Aplikasi web menemukan API melalui {url.api}.
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- Setiap proses adalah tab terminal yang dapat Anda buka, baca, dan ketik, jika Anda memiliki akses tulis ke setiap repositori dalam space (lihat Siapa yang dapat menyimpan apa). Menutup tab tidak menghentikannya.
readymenerimahttp(URL lengkap),tcp(host:port), ataulogMatch(ekspresi reguler).restartbernilaion-failure(default),always, ataunever.restartOnmemulai ulang proses saat jalur yang berubah cocok.optionsmenjadi formulir pada Mulai, danagentDefaultberlaku untuk eksekusi yang dimulai agen.
Contoh: aplikasi desktop
Bagian berjudul “Contoh: aplikasi desktop”Aplikasi desktop dengan langkah build. Aplikasi bekerja sama saja apa pun teknologinya, karena Control Center bekerja di tingkat jendela OS dan tidak memerlukan hook atau SDK di aplikasi.
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}Aplikasi tidak dimulai bersama lingkungan. Seseorang mengklik Luncurkan, dan prepare berjalan lebih dulu. Bangun ulang & luncurkan ulang menjalankan pasangan itu lagi. enabledWhen berlaku untuk aplikasi dan untuk tugas prepare-nya, dan Luncurkan ditolak selama salah satunya nonaktif. Aplikasi dianggap berjalan selama ada proses dalam grup prosesnya yang berjalan, jadi peluncur yang memulai aplikasi lalu keluar tidak masalah. Jika semuanya hilang dalam sekitar 5 detik setelah Luncurkan, aplikasi tampil gagal dengan baris log terakhirnya. Setelah itu, keluar bersih tampil sebagai tertutup dan crash menampilkan baris log terakhir, dan keduanya tidak memulai ulangnya. Restart server menutup aplikasi dan tidak pernah meluncurkannya kembali, dan penghentian saat diam membiarkan aplikasi yang berjalan.
Izin dan batasan aplikasi desktop
Bagian berjudul “Izin dan batasan aplikasi desktop”- Di macOS, berikan Control Center izin Perekaman Layar dan Aksesibilitas satu kali di Pengaturan Sistem. Host server memerlukan sesi GUI: server headless menolak meluncurkan aplikasi.
- Luncurkan biner secara langsung.
open -amenyerahkan aplikasi ke LaunchServices dan aplikasi keluar dari pohon proses yang dilacak Control Center, sehingga aplikasi tampil gagal tepat setelah diluncurkan. - Jendela tetap berada di layar. macOS tidak menangkap jendela yang diparkir di luar semua layar, sehingga aplikasi yang digunakan agen terlihat di layar server. Fokus tidak diperlukan.
"isolate": "home"memberi aplikasi direktori home pribadi melaluiHOME,XDG_*, danCFFIXED_USER_HOME, sehingga salinan dari dua space dapat berjalan berdampingan.NSUserDefaultstidak terisolasi, sehingga preferensi Cocoa danshared_preferencesFlutter tetap dibagi antar salinan.isolatehanya berlaku untuk proses yang diluncurkan. Peluncur toolchain sepertiflutter runmembutuhkan home yang sebenarnya, jadi pasangkanisolatedengan biner hasil build. Jika aplikasi memiliki pengaturan sendiri, seperti--user-data-dir, utamakan itu.- Agen mengendalikan jendela dengan
app_use, yang hanya dapat mencapai pohon proses lingkungan ini. Agen melihat jendela, bukan desktop. Peluncuran oleh agen melewati kebijakan tindakan dan default-nya bertanya, dan input agen berhenti saat seseorang memegang kendali. "input": "background"(default) mengirim peristiwa ke proses."foreground"mengaktifkan jendela dan mengambil alih kursor.
Tugas worktree
Bagian berjudul “Tugas worktree”Tugas provision dan archive menjalankan penyiapan dan pembongkaran repo bersama worktree-nya. Ikon di baris repo pada Pengaturan → Ruang kerja → Repositori membuka definisi repo tersebut.
Tugas ini mengikuti worktree, bukan lingkungan, sehingga berjalan di space tempat tidak ada yang mengklik Mulai:
provision |
archive |
|
|---|---|---|
| Berjalan | Saat worktree peran dibuat, di space mana pun | Tepat sebelum worktree itu dihancurkan |
| Saat gagal | Provisioning gagal dan worktree dihancurkan | Dicatat, tidak pernah memblokir penghapusan |
| Batas waktu default | 5 menit | 2 menit |
| Melihat | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Sama |
Repo tanpa stack hanya membutuhkan definisi yang berisi tugasnya. Karena tidak ada yang perlu dimulai, peran jangkar tidak diperlukan:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Belum ada lingkungan, sehingga tugas ini tidak dapat memakai
{name},{port.*},{url.*},{opt.*}, atauenabledWhen, dan tidak mendapatkanenvdefinisi. - Hanya satu definisi yang boleh memiliki tugas
provisiondanarchiveuntuk sebuah repo. Definisi lain tetap boleh mengikatnya untuk hal lainnya. "when": ["provision", "change"]juga memasang ulang saat lockfile berubah.- Tugas berjalan untuk worktree dari peran
cwd-nya, sehingga definisi multi-repo dapat menyiapkan setiap repo secara terpisah. - Eksekusi uji menyetel
CC_SCRIPT_TEST=1. Percobaan ulang dimulai dari worktree bersih, jadi tulis tugas yang tahan dijalankan ulang.
Agen tidak pernah mendapatkan soket Docker. Di space dengan definisi yang memenuhi syarat, eksekusi mendapatkan cc-env di PATH-nya. Space berasal dari eksekusi, sehingga agen hanya dapat bertindak pada lingkungannya sendiri, dan setiap perintah melewati kebijakan tindakan.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>Dengan komponen compose, shim docker juga mengizinkan docker compose dengan ps, logs, exec, port, restart, dan top, dan hanya terhadap proyek compose milik lingkungan ini. Tidak boleh ada flag sebelum kata kerja, dan setiap kata kerja menerima sejumlah kecil opsi: logs tidak dapat mengikuti output, dan exec hanya menerima -T (atau --no-tty). Opsi yang mengarahkan compose ke berkas atau proyek lain (-f, -p, --project-directory, --env-file, --profile) ditolak di mana pun muncul. Yang lain keluar dengan kode 5 dan “not available in Control Center agent runs”.
Repo yang skill-nya memanggil alatnya sendiri dapat terus melakukannya. Blok agentPassthrough pada komponen cli mendeklarasikan perintah yang boleh dijalankan agen. Hanya perintah yang dideklarasikan oleh definisi yang disetujui yang diteruskan, dan setiap perintah berjalan di host, sehingga berlaku aturan Jalankan perintah di host, yang secara bawaan meminta izin terlebih dahulu:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps menyebut operasi yang kebijakannya berlaku. positionalName memaksa argumen itu ke lingkungan space ini, nameFilter memfilter output JSON untuknya, dan setiap nilai pathFlags harus mengarah ke dalam worktree eksekusi. Perintah yang tidak cocok dengan aturan apa pun keluar dengan kode 5.
Operasi yang sama tersedia sebagai alat: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app, dan environment_stop_app. Agen dalam sandbox mencapai port mereka secara langsung dan nama host lingkungan mereka melalui proxy eksekusi, jadi minta mereka membaca endpoint dari environment_status alih-alih menebak URL.
Pull request dari fork
Bagian berjudul “Pull request dari fork”Kode PR dari fork tidak tepercaya, dan pada penempatan host kode itu berjalan sebagai pengguna OS server. policy.forkPrs menentukan yang terjadi:
| Nilai | Efek | Default untuk |
|---|---|---|
rig |
File compose berjalan di VM tanpa pertanyaan | Definisi yang hanya memiliki komponen compose dan task |
approval |
Setiap mulai memerlukan admin | Semua definisi lain |
deny |
Ditolak | Tidak ada |
seedFilestidak pernah disalin untuk fork, karena biasanya berisi rahasia. File compose yang mengikat salah satunya melaporkan file yang hilang berdasarkan nama.- Tugas
provisiondanarchivedilewati kecuali kebijakannyarig, dan dalam hal itu tugas berjalan di VM. - Pada penempatan host,
privileged, namespace host, bind soket Docker,devices, dan bind di luar worktree space ditolak pada fork. Di space tepercaya, hal itu hanya memberi peringatan.
Penempatan rig
Bagian berjudul “Penempatan rig”"placement": "rig" menjalankan komponen compose dan task di microVM khusus. Definisi dengan komponen process, cli, atau app tidak memenuhi syarat. File compose berjalan tanpa perubahan, tanpa soket Docker host dan tanpa kredensial operator, dan akses jaringan dibatasi pada registri yang dibutuhkan image-nya. Worktree dipasang secara langsung.
- Guest arm64. Guest adalah arm64 di Apple Silicon, sehingga image yang hanya amd64 tidak akan berjalan.
- Registri privat ditolak. Guest tidak memiliki kredensial registri, sehingga image di registri di luar yang publik dikenal ditolak sebelum VM menyala. Repositori privat di registri publik gagal saat guest menariknya.
- Penyimpanan 16 GiB. Semua image dan volume stack berbagi satu disk 16 GiB, dan tidak dapat diperbesar.
- Boot pertama lambat. Lapisan image bersifat per VM, sehingga boot pertama menarik semuanya. Rig yang dihentikan mempertahankan disknya.
- Image dasar harus dapat dibaca. Dockerfile yang menyebut image dasarnya melalui variabel tidak dapat direncanakan, karena akses jaringan ditetapkan saat boot.
- Masa hidup.
policy.rigTtlHoursmengakhiri VM, secara default setelah 24 jam.
Kontrak status untuk pembuat alat
Bagian berjudul “Kontrak status untuk pembuat alat”Komponen cli tanpa statusMap mengharapkan kontrak bawaan, cc-env/1. Kata kerja status mencetak objek ini ke stdout:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}statebernilaiready,starting,stopped,failed, ataumissing.missingmengarah kecreate, sedangkanstoppeddanfailedmengarah kestart. Laporkanmissingdengan kode keluar 0:statusyang gagal dihitung sebagaifailed.- Hanya
stateyang diperlukan. Bidang yang tidak dikenal diabaikan, dan output yang tidak dapat diurai tampil sebagai menurun, dengan teks mentah sebagai detail. - URL harus berupa loopback,
*.localhost, atau berada di bawahrouting.domain, jika tidak URL dibuang. needsRecreate: truemenampilkan Buat ulang, yang membuang data. Control Center tidak pernah bertindak sendiri berdasarkan ini.- Kata kerja
listmencetak array JSON berisi nama, atau objek denganname.
Kode keluar berlaku untuk setiap kata kerja:
| Kode | Arti |
|---|---|
| 0 | OK |
| 3 | Jawaban diperlukan di terminal, misalnya kata sandi sudo. Kata kerja yang tercantum di interactive dijalankan ulang di tab terminal untuk orang yang menekan Mulai. Jika tidak, Jalankan di terminal membuka terminal space dengan command alat sudah diketik tetapi belum dijalankan, lalu Coba lagi mencoba lagi. Control Center tidak pernah menjalankan sudo dan tidak pernah menjawab prompt |
| 4 | Perlu masuk. command alat menjelaskan caranya |
| 5 | Sesuatu yang bergantung padanya tidak tersedia, misalnya runtime kontainer yang tidak berjalan |
| Lainnya | Kegagalan |
Kode 3, 4, dan 5 bukan kegagalan. Lingkungan menampilkan Perlu tindakan dan menunggu, dan mulai berikutnya melanjutkan dari titik tempat mulai tadi berhenti. Tugas yang keluar dengan salah satu kode tersebut memiliki arti yang sama.
Kemajuan dikirim ke stderr sebagai JSON yang dipisahkan baris:
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}Saat lingkungan dimulai, panel menampilkan komponen yang dilalui proses mulai, masing-masing dengan spinner, tanda centang, atau tanda silang. Baris step menyatakan apa yang sedang dilakukan alat sekarang, dan label-nya tampil di bawah baris alat itu sendiri; langkah tidak pernah menambah baris. state sebuah langkah adalah pending, running, done, atau failed, dan langkah tanpa state dianggap sedang berjalan. Langkah yang melaporkan lagi dengan id yang sama (berupa string atau angka, atau dengan label yang sama jika tanpa id) menggantikan apa yang dikatakannya sebelumnya, sehingga alat dengan satu spinner dapat mempertahankan satu id dan mengubah label. Tanpa id, langkah berurutan: langkah baru mengakhiri langkah sebelumnya. Saat perintah keluar, langkah yang masih berjalan berakhir sesuai cara perintah itu berakhir.
Baris log memuat satu baris keluaran alat yang dibungkus JSON, dan dibaca sebagai keluaran teks biasa. Baris note masuk ke output proses, dan yang memiliki "level": "warn" juga tetap ada di lingkungan sebagai peringatan. Baris terakhir bertipe error menjadi galat terstruktur, dengan command ditawarkan untuk disalin, dan 12 baris keluaran terakhir tampil di bawah message-nya. Tanpanya, Control Center menampilkan 20 baris stderr terakhir. Apa pun yang bukan JSON adalah output log biasa.