게시

​

개요

• 타르볼 배포 — 내부 또는 비공개 사용을 위해 특정 Twenty 서버에 앱을 직접 업로드합니다.
• npm에 게시 — 모든 워크스페이스가 검색하고 설치할 수 있도록 Twenty 마켓플레이스에 앱을 등재합니다.

​

앱 빌드

yarn twenty dev:build

​

서버에 배포(타르볼)

​

사전 준비

yarn twenty remote:add --url https://your-twenty-server.com --as production

​

배포

yarn twenty app:publish --private
# To deploy to a specific remote:
# yarn twenty app:publish --private --remote production

​

배포된 앱 공유

1. 설정 > 애플리케이션 > 등록으로 이동하여 앱을 엽니다
2. Distribution 탭에서 공유 링크 복사를 클릭합니다
3. 이 링크를 다른 워크스페이스의 사용자와 공유하세요 — 해당 앱의 설치 페이지로 바로 이동합니다

​

버전 관리

1. package.json의 version 필드를 올리세요(예: 1.2.3 → 1.2.4, 1.3.0, 또는 2.0.0)
2. yarn twenty app:publish --private(또는 yarn twenty app:publish --private --remote production)를 실행합니다.
3. 앱을 설치한 워크스페이스는 설정에서 사용 가능한 업그레이드를 확인할 수 있습니다

​

서버 버전 호환성

{
  "name": "twenty-my-app",
  "version": "1.0.0",
  "engines": {
    "node": "^24.5.0",
    "twenty": ">=2.3.0"
  }
}

• engines.twenty가 설정되어 있고 대상 서버의 버전이 해당 범위를 충족하지 않으면, 배포(tarball 업로드) 또는 설치가 SERVER_VERSION_INCOMPATIBLE 오류와 함께 거부되며 필요한 범위와 실제 서버 버전을 모두 나타내는 메시지가 표시됩니다.
• engines.twenty가 설정되어 있지 않으면, 앱은 모든 서버 버전에서 허용됩니다(기존 앱과 하위 호환).
• 서버에 APP_VERSION이 구성되어 있지 않으면, 검사가 생략됩니다.

​

자동화된 CI/CD (스캐폴드된 워크플로)

​

CI — ci.yml

1. 앱의 소스 코드를 체크아웃합니다.
2. twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main 컴포지트 액션을 사용해 격리된 Twenty 테스트 인스턴스를 생성합니다(CI에서 yarn twenty docker:start --test와 동등합니다).
3. Corepack을 활성화하고, .nvmrc에 따라 Node.js를 설정하며, yarn install --immutable로 의존성을 설치합니다.
4. 생성된 인스턴스에서 TWENTY_API_URL과 TWENTY_API_KEY를 전달하여 실제 서버와 통신할 수 있도록 yarn test를 실행합니다.

• TWENTY_VERSION(환경 변수, 기본값 latest) — ci.yml에서 이 값을 수정하여 CI에서 사용하는 Twenty 서버 버전을 고정합니다.
• 동시 실행은 github.ref로 그룹화되며, 새 푸시가 발생하면 진행 중인 실행을 취소합니다.

​

CD — cd.yml

1. 라벨이 지정된 PR의 경우 PR 헤드, 아니면 푸시된 커밋을 체크아웃합니다.
2. twentyhq/twenty/.github/actions/deploy-twenty-app@main를 실행합니다 — CI에서의 yarn twenty app:publish --private에 해당합니다.
3. twentyhq/twenty/.github/actions/install-twenty-app@main를 실행하여 새로 배포된 버전을 대상 워크스페이스에 설치합니다.

​

재사용 가능한 액션 고정하기

​

npm에 게시

​

요구 사항

• npm 계정
• package.json의 keywords 배열에 있는 twenty-app 키워드(수동으로 추가하세요 — create-twenty-app 템플릿에 기본적으로 포함되어 있지 않습니다)

{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

​

마켓플레이스 메타데이터

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});

​

권장 스크린샷 크기

​

게시

yarn twenty app:publish

yarn twenty app:publish --tag beta

​

마켓플레이스 검색 방식

yarn twenty dev:catalog-sync
# To target a specific remote:
# yarn twenty dev:catalog-sync --remote production

​

CI 게시

name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty dev:build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output

​

앱 설치

yarn twenty app:install