setup

name	setup
description	Start DeployGate onboarding — set up app distribution from first upload to team-wide deployment
allowed-tools	mcp__deploygate__* Bash(./gradlew:*) Bash(xcodebuild:*) Bash(fastlane:*) Bash(security find-identity:*) Bash(git rev-parse:*) Bash(which:*) Bash(mkdir:*) Bash(cp:*) Bash(zip:*) Bash(cd:*) Bash(ls:*) Read Glob AskUserQuestion

Response Language

Detect the user's language from their first message in the conversation. If they wrote in Japanese, use the (ja) block at every user-facing location below. Otherwise (English or any other language), use the (en) block. If unsure, default to (en).

User-facing locations are written as paired blocks marked (en) and (ja). Use only one — never both. This applies to: AskUserQuestion text, progress-display labels, and any prose you quote to the user. Internal instructions, code blocks, file paths, tool names, and JSON examples stay English regardless of language.

DeployGate Onboarding

Guide users through setting up DeployGate for app distribution — from first upload to team-wide deployment.

When to use

When the user wants to:

• Set up DeployGate for the first time
• Upload and distribute an app
• Get started with DeployGate

Reference files

Load these on demand when the flow reaches the matching step. Do NOT preload them — each file is substantial and wastes context if unused.

• references/terminology.md — Read this first, before writing any user-facing response. Defines the user-facing terms (Workspace / Project / Team / Shared Team) and their Japanese equivalents.
• references/ios-build.md — iOS build detail: fastlane vs xcodebuild, code signing pre-flight, Personal Team pitfall. Read when handling iOS in Step 2.
• references/ios-udid.md — Step 5b UDID registration flow (fastlane register_devices / sigh). Read when a tester cannot install an Ad Hoc build.
• references/next-steps.md — Phase 2+ guidance (CI/CD, SDK, team expansion). Read after Phase 1 completes.
• references/troubleshooting.md — troubleshooting table. Read on error.

Progress Display

At the beginning of each step, display a progress indicator. Use ✅ for completed, ▶ for current, and ○ for upcoming. Android skips Step 5.

Android example (at Step 3) — (en):

📋 Phase 1: DeployGate Setup [3/4]
  Step 1 ✅ Account creation
  Step 2 ✅ App upload
  Step 3 ▶  Distribution page        ← now
  Step 4 ○  Notification setup

Android example (at Step 3) — (ja):

📋 Phase 1: DeployGate セットアップ [3/4]
  Step 1 ✅ アカウント作成
  Step 2 ✅ アプリのアップロード
  Step 3 ▶  配布ページの作成        ← now
  Step 4 ○  通知連携の設定

iOS example (at Step 3) — (en):

📋 Phase 1: DeployGate Setup [3/5]
  Step 1 ✅ Account creation
  Step 2 ✅ App upload
  Step 3 ▶  Distribution page        ← now
  Step 4 ○  Notification setup
  Step 5 ○  iOS device setup

iOS example (at Step 3) — (ja):

📋 Phase 1: DeployGate セットアップ [3/5]
  Step 1 ✅ アカウント作成
  Step 2 ✅ アプリのアップロード
  Step 3 ▶  配布ページの作成        ← now
  Step 4 ○  通知連携の設定
  Step 5 ○  iOS端末セットアップ

Show this every time you begin or return to a step. When Phase 1 completes, keep the [5/5] (iOS) or [4/4] (Android) header and mark every step ✅ — do NOT replace the numeric ratio with [完了] or similar.

User Input Collection

Use the AskUserQuestion tool at key decision points — each section below specifies when.

Initial Assessment

Before starting, detect the platform automatically, then use AskUserQuestion to confirm the user's situation:

1. Platform auto-detection. Run ls in the project root (do NOT use Glob for iOS — *.xcodeproj and *.xcworkspace are macOS bundle directories and Glob will return zero matches). Inspect the output:

   • Contains build.gradle or build.gradle.kts → Android candidate
   • Contains any name ending in .xcodeproj or .xcworkspace → iOS candidate
   • If neither is visible at the root, also ls any likely platform subdirectories that appear in the root listing (e.g. app-ios/, ios/, iosApp/, app-android/, android/). KMP / Kotlin Multiplatform and many multi-module repos nest platform projects one level deep — the .xcodeproj is often inside app-ios/, the Android module inside app-android/
   • Both platforms detected (at root or in subdirs) → multi-platform project

2. Use AskUserQuestion to ask:

   • Question 1 (en): "Do you have a DeployGate account?" (header: "Account")
     • "Yes, I have one" — Continue with browser-based login
     • "No, not yet" — Start with account creation
   • Question 1 (ja): "DeployGate のアカウントはお持ちですか？" (header: "アカウント")
     • "はい、持っています" — ブラウザ認証でログインしてセットアップを続けます
     • "いいえ、まだです" — アカウント作成から始めます

   If both platforms are detected, add a second question:

   • Question 2 (en): "Which platform should we set up first?" (header: "Platform")
     • "Android" / "iOS" / "Both"
   • Question 2 (ja): "どのプラットフォームからセットアップしますか？" (header: "プラットフォーム")
     • "Android" / "iOS" / "両方"

3. Is there source code available? If no, the user must provide a pre-built binary.

API Identifiers (used throughout Phase 1)

DeployGate has two identifier slugs you will reuse across tool calls. Both come from the get_user_info / login_wait response. Read terminology.md first for the user-facing names; this section is just the API-side mapping.

Response shape (simplified):

[
  {
    "name": "example-workspace",        // workspace slug (legacy: "enterprise")
    "groups": [
      { "name": "shaker-app", ... }      // project slug (legacy: "organization")
    ]
  }
]

Mapping — use these consistently:

Skill placeholder	Source field	Used in
owner_name	project slug (groups[i].name) — or the user's own login name for a personal account	upload_app, create_distribution, get_notification_settings_url, member tools
{ENTERPRISE_NAME}	workspace slug (top-level name)	Instant Device enable URL only
app_id	package_name from the upload_app response	create_distribution

If the user belongs to multiple projects (more than one entry in groups), ask once at Step 1 which project to use and reuse that choice for every subsequent tool call — do not re-prompt at Step 2.

Phase 1: Distribution Setup

Step 1: Account Creation

Login is browser-based via a device authorization code. The user never pastes a token.

If the user already has an account:

1. Call login_start. It returns a URL (format: https://deploygate.com/app/sessions/codes?code=XXXXXXXX) and a short code. Present the URL to the user and ask them to open it in a browser where they are signed in to DeployGate, then approve the login.
2. Call login_wait immediately after — it blocks until the user approves (or the code expires in 5 minutes). On success it returns workspace/project info and saves the token to ~/.config/deploygate/token (0600).
3. If login_wait returns an error (rejected, expired, nonce mismatch), call login_start again and retry.

If the user doesn't have a DeployGate account:

1. Direct them to sign up: https://deploygate.com/app/register/signup?via=agent-plugin
2. After signup, run the same login_start → login_wait flow described above.

The saved token persists across future agent sessions — the user does not need to log in again unless they run logout or the token is revoked server-side.

If login_wait or any later tool returns "stored token is invalid," the local token file has already been cleared; the user just needs to call login_start again.

Step 2: Build and Upload

Use the owner_name (project slug) chosen at Step 1. If it was not captured, call get_user_info now. See the API Identifiers section for the mapping.

Enable Instant Device (Beta): Instant Device (browser-based app preview) is beta and must be enabled per workspace. Present this URL as the first thing in Step 2, before reading ios-build.md or asking the build-method question — the user clicks it once and you proceed in parallel without waiting:

https://deploygate.com/app/enterprises/{ENTERPRISE_NAME}/instant-device

Substitute {ENTERPRISE_NAME} per the API Identifiers section (workspace slug). The action is idempotent; do not block on confirmation.

Android:

./gradlew assembleDebug

Output path depends on module layout:

• Single-module (module name app): app/build/outputs/apk/debug/app-debug.apk
• Multi-module / KMP (e.g. module app-android): <module>/build/outputs/apk/debug/<module>-debug.apk
• With product flavors (e.g. dev / prod): adds a flavor segment — <module>/build/outputs/apk/<flavor>/debug/<module>-<flavor>-debug.apk

Check settings.gradle.kts / settings.gradle for the app module name. If the project has multiple Android modules, scope the task: ./gradlew :<app-module>:assembleDebug (e.g. ./gradlew :app-android:assembleDebug). After the build, ask the user for the exact APK path before calling upload_app rather than guessing.

IMPORTANT: Do NOT use APKs from Android Studio's Instant Run / Apply Changes — these are incomplete. Always use a full Gradle build.

iOS: Read references/ios-build.md for the full build procedure (fastlane vs xcodebuild, code signing pre-flight, simulator zip for Instant Device). The IPA is required; the simulator zip is an optional addition. Do NOT suggest uploading only the simulator zip as a workaround for a failing IPA build.

Upload using the upload_app tool:

• owner_name: from get_user_info
• file_path: path to the IPA / APK / AAB
• ios_simulator_zip: (iOS only) path to the simulator .zip if built
• message: include Git info — e.g. "feature/login (abc1234)" or "PR #42: Login redesign (abc1234)"

The response contains package_name (bundle identifier on iOS, package name on Android) — you will pass this as app_id in Step 3.

Auto-detect Git info if available:

git rev-parse --short HEAD       # commit hash
git rev-parse --abbrev-ref HEAD  # branch name

Step 3: Create Distribution Page

First, use AskUserQuestion:

• Question (en): "What is the purpose of this distribution page?" (header: "Distribution purpose")
  • "Development team (Development)" — A page for developers to verify the latest builds
  • "QA testing (QA Build)" — A page for testers to run QA
  • "Beta (Beta)" — A page for internal/external beta testers
• Question (ja): "配布ページの用途を選択してください" (header: "配布用途")
  • "開発チーム向け (Development)" — 開発メンバーが最新ビルドを確認するための配布ページ
  • "QA テスト向け (QA Build)" — テスターがテストするための配布ページ
  • "ベータ版 (Beta)" — 社内・外部ベータテスター向けの配布ページ

Then use create_distribution:

• owner_name: same as upload
• platform: "ios" or "android"
• app_id: the package_name field from the upload response
• title: based on the user's choice (e.g. "Development", "QA Build", "Beta")

The response includes access_key. The distribution page URL is:

https://deploygate.com/distributions/{access_key}

Share this URL with testers. They can:

• Mobile: install the app directly
• PC: preview via Instant Device in a browser (no device needed)

Instant Device requires login. Testers must be DeployGate members to preview. Member invitation is Phase 4 work — defer entirely. Mention it in one line — (en) "Previewing with Instant Device requires team invitations from Phase 4." / (ja) "Instant Device でのプレビューには Phase 4 のチーム招待が必要です" — and move on; do NOT call add_member in Phase 1 regardless of what the user says.

If the app is an iOS Development or Ad Hoc build (not In-House/Enterprise), tell the user:

(en):

When testers open the distribution page link in Safari, they'll be prompted to install the DeployGate configuration profile. Installing the profile registers their device's UDID with DeployGate.

For Ad Hoc / Development builds, testers cannot install on a device unless their UDID is in the Provisioning Profile. Share the link first so they install the profile. If you need physical-device installs, do UDID registration in Step 5 (skip Step 5 if Instant Device browser preview is enough).

(ja):

テスターが配布ページのリンクをSafariで開くと、DeployGateの構成プロファイルのインストールを求められます。プロファイルをインストールすると、そのデバイスのUDIDがDeployGateに登録されます。

Ad Hoc / Development ビルドでは、テスターの UDID が Provisioning Profile に含まれていないと実機インストールできません。まずリンクを共有してプロファイルをインストールしてもらってください。実機インストールが必要な場合は Step 5 で UDID 登録を行います（テスターが Instant Device ブラウザプレビューのみで十分なら Step 5 はスキップ可）。

Step 4: Notification Setup

Do not skip this step. Complete it before moving to Step 5.

Notifications enable:

• Automatic alerts when new builds are uploaded
• Notifications when testers install the app
• Visibility into team activity

Use get_notification_settings_url with level: "distribution" and the access_key from Step 3. The tool returns a text message containing the URL — extract the URL verbatim and share it with the user; do not reformat or add query parameters.

Tell the user:

• (en): "Open this URL in your browser to connect Slack, Microsoft Teams, or Chatwork. The setup takes about 1-2 minutes."
• (ja): "このURLをブラウザで開いて Slack / Microsoft Teams / Chatwork と連携してください。設定は1〜2分で完了します。"

After setup, verify by uploading a test build — a notification should arrive in the connected channel.

Once notification setup is confirmed, proceed to Step 5 (if iOS) or the Phase 1 Completion Check (if Android).

Step 5: iOS Device Setup (if applicable)

Prerequisite: Complete Step 4 before starting this step.

Skip for Android. For iOS, use AskUserQuestion:

• Question (en): "Do you need to install the app on testers' physical iOS devices?" (header: "Physical-device test")
  • "Yes, install on devices" — Register UDIDs and update the Provisioning Profile
  • "No, Instant Device (browser preview) is enough" — Proceed to the Phase 1 completion check
• Question (ja): "テスターの iOS 実機にアプリをインストールする必要がありますか？" (header: "実機テスト")
  • "はい、実機にインストールしたい" — UDID 登録と Provisioning Profile の更新を行います
  • "いいえ、Instant Device（ブラウザプレビュー）で十分" — Phase 1 完了チェックに進みます

If the user chooses Instant Device only, skip to the completion check.

5a: Tester Profile Installation

Share the distribution page link with testers and guide them through:

1. Open the distribution page link in Safari (other browsers are not supported)
2. Install the DeployGate configuration profile
3. Settings → General → VPN & Device Management → Downloaded Profile → Install
4. Enter the device passcode (not the DeployGate password)

When a tester installs the profile, a notification like "xxx joined 'yyy'" appears in the chat channel configured in Step 4 — this signals the tester is ready.

5b: UDID Registration (Ad Hoc or Development)

If a tester's device UDID is not in the provisioning profile, they see an error asking to contact the developer. Both Ad Hoc and Development builds use device-scoped profiles, so UDID registration applies to both. (In-House / Enterprise builds bypass this — all devices are allowed.)

Codex can automate the entire UDID registration process. Read references/ios-udid.md for the full fastlane-based workflow (get_udids → fastlane register_devices → fastlane sigh → rebuild → re-upload with the same distribution_key).

Phase 1 Completion Check

Before declaring Phase 1 complete, use AskUserQuestion:

• Question 1 (en): "Were testers able to access the app?" (header: "App check", multiSelect: false)

  • "Yes, confirmed" — Verified launch via Instant Device or installed app
  • "Not yet" — Share the distribution page link with testers and follow up
  • "Hitting a problem" — Move to troubleshooting

• Question 1 (ja): "テスターはアプリにアクセスできましたか？" (header: "アプリ確認", multiSelect: false)

  • "はい、確認できました" — Instant Device またはインストールで起動確認済み
  • "まだ確認できていない" — テスターに配布ページのリンクを共有して確認してもらいます
  • "問題が発生している" — トラブルシューティングを行います

• Question 2 (en): "Did the build-upload notification reach the channel you set up in Step 4?" (header: "Notification check", multiSelect: false)

  • "Yes, received" / "No, not received" / "Skipped notification setup"

• Question 2 (ja): "ビルドアップロード時に通知は届きましたか？（Step 4 で設定したチャンネル）" (header: "通知確認", multiSelect: false)

  • "はい、届きました" / "いいえ、届いていない" / "通知設定をスキップした"

Only after both are confirmed, say:

• (en): "Phase 1 is complete — your app is being distributed to testers via DeployGate."
• (ja): "Phase 1 が完了しました — アプリは DeployGate 経由でテスターに配布されています。"

If the user reports issues, read references/troubleshooting.md before re-asking.

Next Steps

After Phase 1 completes, read references/next-steps.md for Phase 2 (CI/CD via the ci-setup skill), Phase 3 (SDK via the sdk-setup skill, Android only), and Phase 4 (team expansion via add_member / create_shared_team / assign_shared_team_to_app).