rorkai/app-store-connect-cli-스킬

asc 워크플로우

CLI 내에서 Lane 스타일의 자동화가 필요할 때 이 스킬을 사용하세요:

• asc workflow validate
• asc workflow list
• asc workflow run

워크플로우는 저장소-로컬 자동화 파일입니다. 신뢰할 수 있는 셸 명령어를 실행하고, 단계 출력은 stderr로 스트리밍하며, stdout은 기계가 읽을 수 있는 JSON으로 유지합니다.

명령어 탐색

항상 다음 플래그를 확인하세요:

asc workflow --help
asc workflow validate --help
asc workflow list --help
asc workflow run --help

엔드-투-엔드 흐름

1. .asc/workflow.json을 작성합니다.
2. 구조와 참조를 검증합니다:

asc workflow validate

3. 공개 워크플로우를 확인합니다:

asc workflow list
asc workflow list --all

4. 실행을 미리 봅니다:

asc workflow run --dry-run beta BUILD_ID:123456789 GROUP_ID:abcdef

5. 실행합니다:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. 복구 가능한 실행이 실패한 경우, JSON 결과의 실행 ID를 사용하여 재개합니다:

asc workflow run release --resume "release-20260312T120000Z-deadbeef"

--resume과 함께 추가 KEY:VALUE 매개변수를 전달하지 마세요. 저장된 워크플로우 파일, 매개변수 및 유지된 출력이 재사용됩니다.

파일 위치 및 형식

• 기본 경로: .asc/workflow.json
• 경로 재정의: asc workflow run --file ./path/to/workflow.json <name>
• JSONC 주석이 지원됩니다.
• 최상위 훅: before_all, after_all, error
• 워크플로우 키: description, private, env, steps
• 단계 형식:
  • 문자열 단축: "echo hello"
  • run 셸 명령어
  • workflow 서브-워크플로우 호출
  • name 레이블
  • if 조건부 변수 이름
  • with 워크플로우-호출 단계의 환경 재정의
  • outputs 이름이 지정된 실행 단계에서 JSON stdout 추출을 위한 맵
  • retry run 단계에 대한 고정 지연 재시도 정책
  • timeout run 단계에 대한 시도당 양수 기간

출력값

실행 단계는 출력값을 선언할 수 있습니다. 명령어는 stdout에 JSON을 출력해야 하므로, 출력값을 생성하는 asc 명령어에는 --output json을 전달하세요.

출력값 참조는 다음을 사용합니다:

${steps.step_name.OUTPUT_NAME}

규칙:

• outputs를 선언하는 단계는 참조에 안전한 name을 가져야 합니다.
• 출력값은 workflow-호출 단계가 아닌 run 단계에서만 허용됩니다.
• 출력값을 생성하는 이름은 동일한 실행 그래프에서 함께 실행될 수 있는 모든 워크플로우에서 고유해야 합니다.
• 유지된 출력값은 워크플로우 실행 상태에 저장되므로, 시크릿을 출력값에 매핑하지 마세요.

제한된 재시도 및 타임아웃

반복해도 안전하다고 판단한 명령어에만 재시도를 추가하세요. 실행기는 명령어를 분류하거나 자체적으로 재시도 변형을 수행하지 않습니다.

{
  "name": "resolve_build",
  "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
  "retry": {
    "max_attempts": 3,
    "delay": "5s"
  },
  "timeout": "2m"
}

retry.max_attempts는 첫 번째 시도를 포함하며 2에서 100 사이여야 합니다. 재시도 지연 및 타임아웃은 24시간을 넘지 않는 양수 기간이어야 합니다. 두 필드는 워크플로우 호출이나 생명주기 훅이 아닌 run 단계에서만 작동합니다.

타임아웃이 재시도 없이 설정된 경우, 명령어가 원격으로 완료되었을 수 있으므로 최종적입니다. 재시도와 타임아웃을 함께 사용하는 것이 다른 시도가 안전하다는 명시적인 신호입니다. 재개하려면 성공적인 체크포인트나 재시도가 활성화된 실패한 단계가 필요합니다. 출력 추출 실패는 재개할 수 없습니다.

런타임 매개변수

asc workflow run <name> [KEY:VALUE ...]는 두 가지 구분자를 모두 지원합니다:

asc workflow run beta VERSION:2.1.0
asc workflow run beta VERSION=2.1.0

반복된 키는 마지막 값이 우선합니다. 셸 명령어에서는 $VERSION과 같은 셸 확장을 통해 매개변수를 참조하세요.

환경 변수 우선순위

메인 워크플로우 실행:

정의.env < 워크플로우.env < CLI 매개변수

with를 사용한 서브-워크플로우 호출:

서브-워크플로우 env < 호출자 env 및 매개변수 < 단계 with

조건부

단계에 "if": "VAR_NAME"을 추가하세요. 참 값은 대소문자를 구분하지 않고 1, true, yes, y, on입니다. 조회는 먼저 병합된 워크플로우 env/매개변수를 확인한 다음 프로세스 환경을 확인합니다.

예제 워크플로우

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "GROUP_ID": ""
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "최신 빌드를 확인하고 TestFlight에 배포합니다",
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "list_groups",
          "run": "asc testflight groups list --app $APP_ID --limit 20 --output json"
        },
        {
          "name": "add_build_to_group",
          "if": "GROUP_ID",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "App Store 버전 검증, 스테이징 및 제출",
      "steps": [
        {
          "name": "validate",
          "run": "asc validate --app $APP_ID --version $VERSION --platform IOS --output json"
        },
        {
          "name": "stage",
          "run": "asc release stage --app $APP_ID --version $VERSION --build $BUILD_ID --metadata-dir ./metadata/version/$VERSION --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build $BUILD_ID --confirm --output json"
        }
      ]
    },
    "publish-appstore": {
      "description": "상위 레벨 업로드 및 App Store 리뷰 제출",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

유용한 호출 방법

asc workflow validate | jq -e '.valid == true'
asc workflow list --pretty
asc workflow list --all --pretty
asc workflow run --dry-run beta BUILD_ID:123 GROUP_ID:grp_abc
asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'
asc workflow run release BUILD_ID:123 SUBMIT_FOR_REVIEW:true
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

안전 규칙

• .asc/workflow.json을 코드처럼 취급하고, 신뢰할 수 있는 워크플로우 파일만 실행하세요.
• 시크릿이 포함된 신뢰할 수 없는 PR의 워크플로우를 실행하지 마세요.
• 워크플로우 파일을 버전 관리에 유지하세요.
• 먼저 검증하고, 다음으로 dry-run을 수행한 후 실행하세요.
• 변경 단계에는 명시적인 ID와 --confirm을 사용하세요.
• asc validate, asc release stage, asc review submit, asc publish appstore를 사용하세요. 제거된 제출 명령어는 사용하지 마세요.