CocoaPods Trunk: 개요, Trunk를 통한 라이브러리 게시

CocoaPods Trunk란?

CocoaPods Trunk는 pod 라이브러리의 중앙 집중식 게시를 위해 2015년에 출시된 서버 인프라입니다. Trunk 이전에는 각 pod가 Git 리포지토리를 통해 배포되었습니다. 개발자는 공개 리포지토리를 만들고, podspec 파일을 추가하고, 중앙 리포지토리 CocoaPods/Specs에 Pull Request를 보내야 했습니다. 이 방식은 수동 검토가 필요했고 업데이트 게시에 지연이 발생했습니다.

Trunk는 게시, 업데이트 및 pod 관리를 위한 통합 API를 제공하여 이러한 문제를 해결했습니다. 이 서비스는 네 가지 핵심 구성 요소를 포함합니다:

• 인증 — 이메일 확인을 통한 등록 및 세션 토큰 관리. 각 개발자는 계정 및 기기에 연결된 고유 토큰을 받습니다.
• 검증 — 구문 분석, 종속성 린팅, 플랫폼 호환성 확인을 포함한 게시 전 podspec 자동 검증.
• 호스팅 — CocoaPods 서버에 pod 메타데이터 및 버전 저장. 소스 코드는 개발자의 Git 리포지토리에 남아 있으며, Trunk는 podspec 파일과 링크만 저장합니다.
• 액세스 관리 — pod 소유자 추가 및 제거, 게시 권한 양도, pod를 더 이상 사용되지 않음으로 표시.

Trunk의 아키텍처는 PostgreSQL 데이터베이스를 갖춘 Ruby on Rails 스택으로 구축되었습니다. 이 서비스는 모든 작업에 JSON 형식의 HTTP API를 사용하며, CLI 클라이언트 pod trunk는 CocoaPods 배포의 일부로 주요 cocoapods gem과 함께 설치됩니다.

현재까지 Trunk를 통해 10만 개 이상의 pod가 게시되었으며, 총 다운로드 수는 500억을 초과합니다. 이 서비스는 전 세계 개발자로부터 매일 수천 건의 게시 및 업데이트 요청을 처리합니다.

등록 및 인증

pod를 게시하기 전에 Trunk에 등록해야 합니다. 프로세스는 pod trunk register 명령어의 한 단계로 구성됩니다:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, iOS 개발'

명령어를 실행하면 지정된 이메일로 확인 링크가 전송됩니다. 링크를 클릭하면 계정이 활성화되고 시스템 키체인(macOS의 Keychain, Linux의 gnome-keyring 또는 이에 상응하는 도구)에 저장되는 세션 토큰이 생성됩니다. 토큰은 이후 모든 pod trunk 작업에서 자동으로 사용됩니다.

--description 매개변수는 선택 사항이지만 권장됩니다 — pod trunk me를 통해 활성 세션을 볼 때 세션 식별에 도움이 됩니다. 여러 머신(워크스테이션, CI 서버)에서 작업하는 경우 설명을 통해 세션을 구분할 수 있습니다.

인증 상태를 확인하려면 다음 명령어를 사용합니다:

pod trunk me

출력에는 이메일, 이름, pod 목록(이미 게시한 경우) 및 활성 세션이 표시됩니다. 결과 예시:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, iOS 개발

CI 서버(GitHub Actions, GitLab CI, Jenkins)에서는 COCOAPODS_TRUNK_TOKEN 환경 변수를 통해 전달되는 토큰으로 인증이 수행됩니다. 토큰은 다음 명령어로 얻을 수 있습니다:

pod trunk me --token-only

이 토큰은 CI 설정에 비밀 변수로 저장되며, 반복 등록 없이 게시 단계에서 사용됩니다. GitHub Actions 예시:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

중요: 토큰은 계정에 연결된 pod 관리에 대한 전체 액세스 권한을 제공합니다. 공개 리포지토리에 게시하거나 타사와 공유하지 마십시오. 유출된 경우 pod trunk remove-session을 통해 또는 CocoaPods 웹사이트 제어판에서 모든 세션을 삭제하여 토큰을 취소할 수 있습니다.

Podspec 준비

podspec 파일(.podspec 또는 .podspec.json)은 메타데이터, 종속성, 플랫폼 정보 및 소스 코드 세부 정보가 포함된 라이브러리 매니페스트입니다. Trunk는 이 파일을 검증 및 pod 등록에 사용합니다. 게시를 위한 최소 podspec은 다음과 같습니다:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = '라이브러리 간단 설명'
  s.description  = '기능 설명이 포함된 자세한 설명'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

podspect의 주요 필드:

• name — pod 이름, Trunk 레지스트리에서 고유해야 합니다. 이름은 선착순으로 등록됩니다 — 이름이 이미 사용 중이면 게시가 거부됩니다.
• version — MAJOR.MINOR.PATCH 형식의 시맨틱 버전. Trunk는 동일한 버전의 재게시를 허용하지 않습니다 — 번호를 올려야 합니다.
• source — Git 리포지토리 링크 및 태그. Trunk는 소스 코드를 저장하지 않으므로 리포지토리를 클론할 수 있어야 합니다.
• platform — 대상 플랫폼(iOS, macOS, tvOS, watchOS) 및 최소 SDK 버전.
• license — 라이선스 유형. MIT, Apache-2.0, BSD 또는 기타 오픈 소스 라이선스를 지정하는 것이 좋습니다.

게시 전에 린터로 podspec의 정확성을 확인하십시오:

pod lib lint MyLibrary.podspec

린터는 구문, 필수 필드, 파일 경로의 정확성 및 종속성 해결 가능성을 확인합니다. 린팅 과정에서 비공개 소스를 사용하는 경우 --sources 플래그를 추가합니다. 네트워크 다운로드를 건너뛰려면(로컬 확인만) --local-only 플래그를 사용합니다.

pod trunk push를 통한 게시

pod 게시를 위한 주요 명령어는 pod trunk push입니다. podspec 파일을 Trunk 서버로 전송하여 전체 검증을 거친 후 퍼블릭 레지스트리에 등록됩니다. 구문:

pod trunk push MyLibrary.podspec

--allow-warnings 플래그는 경고가 있어도 게시를 허용합니다. 기본적으로 경고가 있으면 게시가 차단됩니다. 라이브러리에 기능에 영향을 주지 않는 알려진 경고가 있는 경우 이 플래그를 사용할 수 있습니다. 중요: 오류는 플래그에 관계없이 항상 게시를 차단합니다.

--synchronous 플래그는 요청을 동기식으로 만듭니다 — 터미널이 서버 측 검증 완료를 기다립니다. 기본적으로 명령어는 제출 직후 제어권을 반환하며, 서버는 비동기식으로 게시를 처리합니다. 동기 모드는 파이프라인의 다음 단계가 게시 성공에 의존하는 CI/CD에서 유용합니다.

--skip-import-validation 플래그는 테스트 프로젝트로의 라이브러리 가져오기 확인을 건너뜁니다. 게시 속도는 빨라지지만 라이브러리가 실제로 컴파일된다는 보장은 없습니다. 이 플래그는 빌드 정확성이 확실한 경우에만 사용하십시오.

일반적인 옵션을 사용한 게시 예시:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

게시에 성공하면 Trunk가 세부 정보가 포함된 JSON을 반환합니다:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

라이브러리는 모든 iOS 또는 macOS 프로젝트에서 Podfile을 통해 설치할 수 있습니다. 일반적으로 CocoaPods 검색 인덱스는 몇 분 내에 업데이트되지만, 드물게 인덱싱에 최대 1시간이 걸릴 수 있습니다.

중요한 제한 사항: 한 번 게시된 pod 버전은 삭제할 수 없습니다. 이는 이미 이 버전을 사용하는 프로젝트가 손상되는 것을 방지하기 위함입니다. 게시에 오류가 있었다면 수정 사항이 포함된 다음 버전을 게시할 수 있지만 롤백은 불가능합니다. 예외는 pod trunk delete로, CocoaPods 직원만 사용할 수 있으며 극단적인 경우(라이선스 위반, 악성 코드)에 사용됩니다.

릴리스 및 액세스 관리

CocoaPods Trunk는 게시된 pod 관리를 위한 여러 명령어를 제공합니다:

소유자 추가

다른 개발자에게 pod 게시 권한을 양도하려면 다음 명령어를 사용합니다:

pod trunk add-owner MyLibrary developer@email.com

실행 후 새 소유자는 pod 관리에 대한 전체 액세스 권한을 얻습니다: 새 버전 게시, 다른 소유자 추가 및 제거, pod를 더 이상 사용되지 않음으로 표시. 등록된 Trunk 사용자라면 누구나 소유자가 될 수 있습니다 — 사전 등록이 필수입니다.

소유자 제거

개발자가 프로젝트를 떠났거나 pod에 대한 액세스 권한이 더 이상 없어야 하는 경우:

pod trunk remove-owner MyLibrary developer@email.com

현재 소유자만 소유자를 제거할 수 있습니다. pod의 마지막 소유자는 제거할 수 없습니다 — 먼저 새 소유자를 추가해야 합니다. 이는 pod가 소유자 없이 방치되는 것을 방지합니다.

pod를 더 이상 사용되지 않음으로 표시

라이브러리가 더 이상 유지 관리되지 않는 경우 더 이상 사용되지 않음(deprecated)으로 표시할 수 있습니다. 레지스트리에서 pod가 제거되지는 않지만 설치 시 사용자에게 경고가 추가됩니다:

pod trunk deprecate MyLibrary

선택적으로 대체 pod를 지정할 수 있습니다:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

더 이상 사용되지 않는 pod를 설치하면 CocoaPods가 터미널에 경고를 표시하고 지정된 대체 항목으로 전환할 것을 권장합니다. 이는 기존 프로젝트 빌드를 손상시키지 않고 라이브러리 지원을 종료하는 올바른 방법입니다.

pod 정보 보기

pod 정보는 pod trunk info 명령어를 통해 확인할 수 있습니다:

pod trunk info MyLibrary

명령어는 모든 pod 버전, 게시 날짜, 소유자 목록 및 상태(활성/더 이상 사용되지 않음)를 표시합니다. 특정 버전의 세부 정보를 보려면 pod spec cat MyLibrary 0.1.0을 사용합니다.

오류 및 해결 방법

Trunk로 작업할 때 개발자는 종종 일반적인 오류를 경험합니다. 가장 일반적인 오류를 살펴보겠습니다:

인증 오류

증상: [!] Authentication failed. You need to register a session first.
원인: 세션 토큰이 없거나 만료됨. 토큰에는 제한된 유효 기간이 있습니다(기본적으로 활동 없이 30일).
해결 방법: pod trunk register your@email.com 'Your Name'을 다시 실행합니다. CI를 사용하는 경우 COCOAPODS_TRUNK_TOKEN 환경 변수가 최신 상태인지 확인하고 필요한 경우 새 토큰을 생성합니다.

버전 충돌

증상: [!] You have already pushed version 0.1.0 for MyLibrary.
원인: 기존 버전을 다시 게시하려는 시도. Trunk는 버전 덮어쓰기를 허용하지 않습니다.
해결 방법: 시맨틱 버전 관리에 따라 podspec에서 버전을 올립니다. podspec에서 실수한 경우 수정 사항이 포함된 다음 버전을 게시합니다.

Podspect 검증 오류

증상: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
원인: source_files 필드의 소스 파일 경로가 잘못됨.
해결 방법: podspec에서 경로를 확인하고, 모든 오류가 해결될 때까지 로컬로 pod lib lint를 실행한 후 게시를 다시 시도합니다. 글로브 패턴 사용: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

연결 시간 초과

증상: [!] Connection to trunk.cocoapods.org failed. Timeout.
원인: 네트워크 문제 또는 Trunk 서버의 일시적인 사용 불가.
해결 방법: 서버 가용성 확인: curl -I https://trunk.cocoapods.org. 서버가 응답하면 몇 분 후에 명령어를 다시 시도합니다. IP가 차단되었을 수 있습니다 — 다른 연결 또는 VPN을 통해 시도하십시오.

pod에 대한 액세스 권한 없음

증상: [!] You do not have permission to push to MyLibrary.
원인: pod의 소유자가 아닙니다. 누군가가 이미 해당 이름으로 pod를 등록한 경우 발생합니다.
해결 방법: 현재 pod 소유자에게 연락하여(pod trunk info MyLibrary를 통해 확인) pod trunk add-owner를 통해 추가해 달라고 요청합니다. pod 이름이 이미 사용 중인 경우 대체 이름을 고려하십시오.