빌드에 버전 정보를 포함시키기

소프트웨어를 사용하는 사람들은 자신이 실행하는 버전을 확인해야 합니다. Coroid는 각 릴리스에 버전과 빌드 번호를 부여하여 이를 빌드하는 파이프라인에 전달한 뒤, 배포된 릴리스가 해당 환경에서 정상적으로 실행되는지 확인합니다.

이 페이지의 모든 설정은 프로젝트별로릴리스 → 릴리스 설정 → 버전 관리.

버전의 출처#

프로젝트별로 하나의 출처를 선택하세요:

• Coroid가 버전을 할당합니다.(기본값): 릴리스를 준비할 때 Coroid가 다음 버전을 제안합니다. 이는 프로젝트에서 배포한 가장 높은 버전의 마지막 숫자를 증가시켜 결정됩니다.1.4.0는1.4.1으로 이어지며, 첫 번째 릴리스는0.1.0. 필요한 경우 다른 버전을 직접 입력할 수 있습니다.
• 저장소에서 값을 읽어옵니다.: Coroid는 릴리스 커밋 시점에 코드에 명시된 버전을 읽어옵니다. 이는VERSION, package.json, app.json(Expo),pubspec.yaml, Android Gradle 파일,Cargo.toml, pyproject.toml및 Xcode 프로젝트에서 값을 추출하거나, 지정한 파일에서만 읽어올 수 있습니다. 만약 해당 파일에 이전 릴리스에서 사용한 버전이 남아 있다면, Coroid는 먼저 버전을 올리도록 요청합니다.
• 내 파이프라인에서 버전을 할당합니다.: CI/CD가 semantic-release나 태그를 이용해 버전을 결정한 뒤, 배포 시점에 이를 보고합니다.

모든 릴리스에는 빌드 번호도 부여됩니다. 빌드 번호는 항상 증가하며 프로젝트 내에서 재사용되지 않는데, 이는 iOS 및 Android 앱 스토어에서 요구하는 사항입니다.CFBundleVersion와 AndroidversionCode.

빌드 과정에서 전달되는 값#

Coroid가 릴리스를 위해 GitHub Actions 워크플로우나 GitLab CI/CD 파이프라인을 시작하면 다음 값들을 전달합니다:

GitHub는 워크플로우에서 선언하지 않은 입력값을 거부합니다. 따라서 Coroid는 이 값들을 해당 워크플로우에서만 사용하도록 전달합니다.coroid_version, coroid_build_number및coroid_release_name는 해당 항목을 요구하는 워크플로우에만 전달됩니다. 선택적 항목으로 선언하세요:

on:
  workflow_dispatch:
    inputs:
      coroid_release_id: { required: true }
      coroid_attempt_id: { required: true }
      coroid_commit_sha: { required: true }
      coroid_environment: { required: true }
      coroid_version: { required: false }
      coroid_build_number: { required: false }
      coroid_release_name: { required: false }

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      APP_VERSION: ${{ inputs.coroid_version || '0.0.0-dev' }}
      APP_BUILD_NUMBER: ${{ inputs.coroid_build_number || '0' }}
      APP_COMMIT: ${{ inputs.coroid_commit_sha || github.sha }}

GitLab는 이 값들을 변수로 전달하므로 별도의 선언이 필요하지 않습니다.

deploy:
  script:
    - export APP_VERSION="${COROID_VERSION:-0.0.0-dev}"
    - export APP_BUILD_NUMBER="${COROID_BUILD_NUMBER:-0}"
    - export APP_COMMIT="${COROID_COMMIT_SHA:-$CI_COMMIT_SHA}"

독립적으로 실행되는 파이프라인은 자체적인 값을 사용할 수 있습니다. 아래에 설명된 대로 배포한 버전을 보고하면 릴리스에 해당 정보가 표시됩니다.

릴리스 매니페스트 작성하기#

모든 플랫폼에서 적용 가능한 가장 간단한 방법은 빌드 과정 중에 작은 파일을 생성한 뒤, 버전이 표시되어야 하는 곳에서 이를 읽어오는 것입니다.

cat > release.json <<EOF
{
  "version": "$APP_VERSION",
  "buildNumber": "$APP_BUILD_NUMBER",
  "commitSha": "$APP_COMMIT",
  "releaseName": "${COROID_RELEASE_NAME:-}",
  "environment": "${COROID_ENVIRONMENT:-local}"
}
EOF

웹 앱이나 서비스의 경우, 이 파일을/version.json에서 제공하세요. 이를 통해 Coroid도 해당 URL을 이용해 값을 확인할 수 있습니다.

활용 예시#

웹 앱 (Next.js, Vite)#

브라우저에서 필요한 값은 번들 빌드 시점에 설정되어야 합니다.

NEXT_PUBLIC_APP_VERSION="$APP_VERSION" NEXT_PUBLIC_APP_COMMIT="$APP_COMMIT" npm run build
VITE_APP_VERSION="$APP_VERSION" npm run build

푸터나 '정보' 화면에process.env.NEXT_PUBLIC_APP_VERSION또는import.meta.env.VITE_APP_VERSION를 표시하고, 빌드 전에 공개 폴더에release.json를 복사해 넣으세요.

서버 및 API#

시작 시점에 값을 읽어와 버전 엔드포인트에서 이를 반환하세요.

app.get('/version.json', (_request, response) => {
  response.json({
    version: process.env.APP_VERSION,
    buildNumber: process.env.APP_BUILD_NUMBER,
    commitSha: process.env.APP_COMMIT,
  });
});

Docker 이미지#

값을 빌드 인수로 전달하고 이미지에 라벨을 지정하면, 실행 중인 컨테이너와 레지스트리 모두에서 버전 정보를 확인할 수 있습니다.

ARG APP_VERSION=0.0.0-dev
ARG APP_COMMIT=unknown
ENV APP_VERSION=$APP_VERSION APP_COMMIT=$APP_COMMIT
LABEL org.opencontainers.image.version=$APP_VERSION \
      org.opencontainers.image.revision=$APP_COMMIT

docker build --build-arg APP_VERSION="$APP_VERSION" --build-arg APP_COMMIT="$APP_COMMIT" .

iOS#

Xcode는 App Store에 표시되는 버전을MARKETING_VERSION에서 읽어오며, 빌드 번호는CURRENT_PROJECT_VERSION:

xcodebuild -scheme App -configuration Release archive \
  MARKETING_VERSION="$APP_VERSION" \
  CURRENT_PROJECT_VERSION="$APP_BUILD_NUMBER"

fastlane을 사용하는 경우,increment_version_number(version_number: ENV["APP_VERSION"])와increment_build_number(build_number: ENV["APP_BUILD_NUMBER"]).

Android#

다음 값을 읽어보세요:app/build.gradle.kts:

android {
    defaultConfig {
        versionName = System.getenv("APP_VERSION") ?: "0.0.0-dev"
        versionCode = (System.getenv("APP_BUILD_NUMBER") ?: "1").toInt()
    }
}

BuildConfig.VERSION_NAME그 후 앱에 버전 정보를 표시합니다.

Flutter#

flutter build appbundle --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"
flutter build ipa --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"

Expo 및 React Native#

다음 값을 읽어보세요:app.config.js:

export default {
  expo: {
    version: process.env.APP_VERSION ?? '0.0.0-dev',
    ios: { buildNumber: process.env.APP_BUILD_NUMBER ?? '1' },
    android: { versionCode: Number(process.env.APP_BUILD_NUMBER ?? 1) },
  },
};

배포한 버전을 보고하세요#

배포 이벤트를 통해 어떤 버전과 빌드가 배포되었는지 알 수 있습니다. 다음을 추가하세요:version및buildNumber기존에 파이프라인에서 전송하는 이벤트에 포함시키세요:

{
  "schemaVersion": 1,
  "eventId": "ci:run-812:production:succeeded",
  "providerRunId": "run-812",
  "projectId": "<project-uuid>",
  "environmentKey": "production",
  "repository": "owner/repository",
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "status": "succeeded",
  "occurredAt": "2026-09-28T12:00:00Z",
  "version": "1.4.0",
  "buildNumber": "42"
}

프로젝트의 파이프라인에서 버전을 할당하는 경우, 릴리스에는 보고된 버전이 적용됩니다. 그렇지 않으면 릴리스 페이지에 보고된 버전이 표시되며, 릴리스와의 차이점도 함께 안내됩니다. Coroid에서 호스팅되는 프로젝트의 경우 다음을 설정하세요:repository프로젝트 ID로 설정하세요.배포 이벤트 및 CI 설정이벤트의 나머지 내용은 여기서 설명합니다.

현재 실행 중인 버전을 확인하세요#

각 환경에 버전 URL을 지정하세요. 예:https://app.example.com/version.json. 배포가 성공하면 Coroid가 해당 URL을 열어 커밋 SHA 또는 버전 정보를 확인합니다. 보고된 커밋은 릴리스 커밋과 일치해야 하며, 그렇지 않으면 버전이 일치해야 합니다. 롤아웃이 완료될 때까지 Coroid는 10분간 계속 확인한 뒤 다음을 표시합니다:확인됨, 다른 버전또는접근 불가아래에 표시됩니다:현재 실행 중인 버전릴리스 페이지의 해당 항목에서 확인할 수 있습니다.

URL은 HTTPS와 공개 주소를 사용해야 합니다. Coroid는 리디렉션을 따르지 않으며 최대 64KB까지만 읽습니다.

Coroid가 설정을 대신 처리하도록 하세요#

버전 표시 기능 설정하기버전 관리 화면에서 '새 작업'을 선택하면 프로젝트에 적용된 스택에 맞춘 요청이 생성됩니다. 에이전트는 빌드 시 위에 명시된 값을 읽어 앱에 버전 정보를 표시하고,release.json를 작성하며, 워크플로우 입력값을 선언하고 README에 관련 내용을 기록합니다. 요청 내용을 검토한 뒤 다른 작업과 동일하게 진행하면 됩니다.

관련 항목#

• 릴리스 설정
• 배포 이벤트 및 CI 설정
• 릴리스