Back to Details

asc-release-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

App Release Workflow

应用发布工作流

How it works

工作原理

The project keeps a release config at 
.asc/release.yml
. Read it first to get platform schemes, version file paths, and locale list.
项目在
.asc/release.yml
中保存发布配置。请先读取该文件以获取平台Scheme、版本文件路径及语言区域列表。

Workflow Steps

工作流步骤

Step 1: Determine what to release

步骤1：确定发布内容

Ask the user (if not clear):
  • Which platform? (ios / macos / both)
  • New version number? (or just bump build number for same version)
  • What's New text? (in primary locale — you'll translate for others)
若信息不明确，请询问用户：
  • 目标平台？（iOS / macOS / 两者）
  • 新版本号？（或仅升级同一版本的构建号）
  • 新增功能文本？（请提供主语言区域的内容，后续将为其他语言区域翻译）

Step 2: Bump version

步骤2：升级版本号

Read the release config to find 
version_file
and 
version_pattern
for the target platform. Also bump 
build_number_file
.
  1. Read the version file, find the current version using the regex pattern
  2. Replace with the new version string
  3. Read the build number file, increment the build number
  4. If multiple platforms share the same build number file, both get bumped
Important: Also update 
CFBundleVersion
and 
CURRENT_PROJECT_VERSION
if they are separate from the build number pattern. Check 
Shared.swift
and 
TargetExtensions.swift
.
读取发布配置，找到目标平台对应的
version_file
和
version_pattern
。同时升级
build_number_file
中的构建号。
  1. 读取版本文件，使用正则表达式匹配当前版本
  2. 替换为新版本字符串
  3. 读取构建号文件，递增构建号
  4. 若多个平台共享同一构建号文件，则同时升级两者的构建号
重要提示： 若
CFBundleVersion
和
CURRENT_PROJECT_VERSION
与构建号规则分离，请同时更新这两个字段。请检查
Shared.swift
和
TargetExtensions.swift
文件。

Step 3: Regenerate project (if needed)

步骤3：重新生成项目（如需要）

Run any commands listed in 
pre_archive
(e.g., 
tuist generate
).
运行
pre_archive
中列出的所有命令（例如
tuist generate
）。

Step 4: Archive, export, upload

步骤4：归档、导出、上传

bash
asc builds archive \
  --scheme <SCHEME> \
  --platform <PLATFORM> \
  --signing-style automatic \
  --team-id <TEAM_ID> \
  --upload \
  --app-id <APP_ID> \
  --version <VERSION> \
  --build-number <BUILD_NUMBER>
bash
asc builds archive \
  --scheme <SCHEME> \
  --platform <PLATFORM> \
  --signing-style automatic \
  --team-id <TEAM_ID> \
  --upload \
  --app-id <APP_ID> \
  --version <VERSION> \
  --build-number <BUILD_NUMBER>

Step 5: Wait for build processing

步骤5：等待构建处理完成

Poll until complete:
bash
asc builds uploads get --upload-id <UPLOAD_ID>
Check the 
state
field. If 
FAILED
, read the 
errors
array and report to the user. Common failures:
  • Missing icon → fix asset catalog
  • Missing entitlements → add sandbox entitlement for macOS
  • CFBundleVersion mismatch → ensure build number matches
轮询直至处理完成：
bash
asc builds uploads get --upload-id <UPLOAD_ID>
检查
state
字段。若状态为
FAILED
，请读取
errors
数组并向用户报告问题。常见失败原因：
  • 缺少图标 → 修复资源目录
  • 缺少权限配置 → 为macOS添加沙箱权限
  • CFBundleVersion不匹配 → 确保构建号一致

Step 6: Link build to version

步骤6：关联构建与版本

bash
undefined
bash
undefined

Find the version in PREPARE_FOR_SUBMISSION state for the platform

查找目标平台下处于PREPARE_FOR_SUBMISSION状态的版本

asc versions list --app-id <APP_ID>
asc versions list --app-id <APP_ID>

Filter for the target platform + PREPARE_FOR_SUBMISSION state

筛选目标平台 + PREPARE_FOR_SUBMISSION状态的版本

Find the build

查找构建记录

asc builds list --app-id <APP_ID>
asc builds list --app-id <APP_ID>

Match by build number

通过构建号匹配目标构建

Link them

关联版本与构建

asc versions set-build --version-id <VERSION_ID> --build-id <BUILD_ID>
undefined
asc versions set-build --version-id <VERSION_ID> --build-id <BUILD_ID>
undefined

Step 7: Update What's New (skip for first version v1.0.0)

步骤7：更新“新增功能”（v1.0.0首个版本可跳过）

For each locale in the config:
bash
asc version-localizations list --version-id <VERSION_ID>
针对配置中的每个语言区域执行以下操作：
bash
asc version-localizations list --version-id <VERSION_ID>

Get localization IDs for each locale

获取各语言区域的本地化ID

asc version-localizations update
--localization-id <LOC_ID>
--whats-new "<TRANSLATED_TEXT>"

Generate What's New text:
- Use the user-provided text as the en-US version
- Translate to each locale maintaining the same tone and formatting
- Keep it concise (2-4 sentences max)
asc version-localizations update
--localization-id <LOC_ID>
--whats-new "<翻译后的文本>"

生成“新增功能”文本的规则：
- 将用户提供的文本作为en-US版本
- 为其他语言区域翻译时保持语气和格式一致
- 内容需简洁（最多2-4句话）

Step 8: Check readiness

步骤8：检查发布就绪状态

bash
asc versions check-readiness --version-id <VERSION_ID>
Report the result to the user. If 
isReadyToSubmit
is true, ask if they want to submit. If not, list what's missing (screenshots, description, etc).
bash
asc versions check-readiness --version-id <VERSION_ID>
向用户报告检查结果。若
isReadyToSubmit
为true，请询问用户是否确认提交。若未就绪，请列出缺失的内容（如截图、描述等）。

Step 9: Submit (if user confirms)

步骤9：提交发布（若用户确认）

bash
asc versions submit --version-id <VERSION_ID>
bash
asc versions submit --version-id <VERSION_ID>

First-time platform setup (one-time only)

首次平台配置（仅需执行一次）

If this is the first release for a platform (e.g., adding macOS to an existing iOS app), additional setup is needed BEFORE the regular workflow:
  1. Provisioning profile — Check if one exists, create if not:
    bash
    asc bundle-ids list --identifier <BUNDLE_ID>
asc certificates list --type MAC_APP_DISTRIBUTION  # or IOS_DISTRIBUTION
asc profiles list --bundle-id-id <BID_ID>
asc profiles create --name "Mac App Store: <BUNDLE_ID>" --type MAC_APP_STORE --bundle-id-id <BID_ID> --certificate-ids <CERT_ID>
  2. Entitlements — macOS requires App Sandbox. Check for 
    .entitlements
    file.
  3. App icon — Verify the platform's asset catalog has icons assigned.
  4. Description — Copy from existing platform if available, adapt for the new platform.
  5. Create version — If no PREPARE_FOR_SUBMISSION version exists:
    bash
    asc versions create --app-id <APP_ID> --platform MAC_OS --version-string 1.0.0
若为某平台首次发布（例如在现有iOS应用中新增macOS版本），请在执行常规工作流前完成以下额外配置：
  1. 配置描述文件 — 检查是否已存在，若不存在则创建：
    bash
    asc bundle-ids list --identifier <BUNDLE_ID>
asc certificates list --type MAC_APP_DISTRIBUTION  # 或IOS_DISTRIBUTION
asc profiles list --bundle-id-id <BID_ID>
asc profiles create --name "Mac App Store: <BUNDLE_ID>" --type MAC_APP_STORE --bundle-id-id <BID_ID> --certificate-ids <CERT_ID>
  2. 权限配置 — macOS需要App Sandbox权限。请检查是否存在
    .entitlements
    文件。
  3. 应用图标 — 确认平台资源目录已配置对应图标。
  4. 应用描述 — 若已有其他平台的描述，可复制后适配新平台。
  5. 创建版本 — 若不存在PREPARE_FOR_SUBMISSION状态的版本，请执行：
    bash
    asc versions create --app-id <APP_ID> --platform MAC_OS --version-string 1.0.0