bitrise-release-management

# Bitrise Release Management Onboarding Get a prospect's first installable build into Release Management and produce a public install page URL they can share with testers or stakeholders. This is the third of three skills in the prospect onboarding journey. ## Why these instructions exist Release Management (RM) is conceptually separate from CI — a "connected app" in RM is its own object with its own UUID, tied to a workspace and optionally to a CI project. The artifact that lives on the CI side does not automatically appear in RM; you have to upload it. This skill is the recipe for that. There's also one piece that the Bitrise MCP doesn't quite finish: the exact response field that contains the rendered public install page URL isn't documented. The skill calls `list_installable_artifacts` after enabling the page and inspects whatever URL field comes back. If the response shape differs from expectation, surface what's actually there — don't fabricate a URL. ## Preconditions - The user has a Bitrise PAT wired into the MCP. Run `me` to confirm. - The user has a CI app and at least one successful build with a distributable artifact (`.ipa`, `.apk`, or `.aab`). If they don't, run `bitrise-ci-onboarding` first. - The user knows their app's bundle ID (iOS) or package name (Android). Apple-style: `com.acme.coolapp`. Both platforms use a similar reverse-DNS format. - For iOS public install pages with truly no Apple-side connection, use `manual_connection: true` (covered below). Otherwise, an App Store Connect / Google Play Console store credential needs to exist at the workspace level — that's a separate setup the prospect may not have done yet. For a PoC walkthrough, default to `manual_connection: true` so the flow doesn't require those credentials. ## The flow ### 1. Confirm context Gather, by asking the user: - **Workspace slug.** Reuse from `bitrise-ci-onboarding` if you ran it. If not, call `list_workspaces` and pick. - **Platform.** `ios` or `android`. The store_app_id format and the artifact type (IPA vs APK/AAB) depend on this. - **Bundle ID / package name.** This becomes `store_app_id` on the connected app. Confirm with the user — typos here mean the install page installs nothing. - **App display name.** Required if you go with `manual_connection: true`. - **The artifact.** Either (a) the slug of a successful CI build whose artifact you'll fetch, or (b) a path to a local IPA/APK/AAB on the user's disk. Path is simpler; build-slug requires extra work to download from CI first. ### 2. Create the connected app Call `create_connected_app`: - `platform`: `ios` or `android` - `store_app_id`: bundle ID / package name - `workspace_slug`: from step 1 - `manual_connection`: `true` (default for the PoC; bypasses App Store / Play credential requirements) - `store_app_name`: required when `manual_connection` is true - `project_id`: omit, and Bitrise auto-creates a new RM project. If the user has an existing RM project they want to attach to, pass its UUID. Capture the returned `connected_app_id` (a UUIDv4). You'll need it for the upload and for enabling the public install page. ### 3. Prepare the artifact If the user gave a local file path, you're set — record `file_name` (the basename), `file_size_bytes` (size on disk). If the user pointed at a CI build slug, you need to fetch the artifact first: - `list_artifacts(app_slug, build_slug)` to find the artifact - `get_artifact(app_slug, build_slug, artifact_slug)` to get the `expiring_download_url` - Download it via shell (`curl`) to a known local path - Then proceed as if the user gave you a local path For iOS, look for `.ipa`. For Android, prefer `.aab` if available (Play-friendly), fall back to `.apk`. ### 4. Generate the upload URL Generate a fresh UUIDv4 client-side as `installable_artifact_id`. The Python and Node MCPs both support this; if you can't generate one, ask the user to provide one. This UUID becomes the artifact's identity in RM. Call `generate_installable_artifact_upload_url`: - `connected_app_id`: from step 2 - `installable_artifact_id`: the UUIDv4 you just generated - `file_name`: e.g., `coolapp-v1.0.0.ipa` - `file_size_bytes`: from step 3 - `branch`: optional; pass the branch the build came from if you know it - `workflow`: optional; pass the workflow name if you know it - `with_public_page`: `true` — turn on the public install page at upload time so you don't need a separate enable call later The response gives `url`, `method`, and `headers`. Treat `headers` as a dict; you must replay each one verbatim on the upload. ### 5. Upload the binary The MCP doesn't have a tool for the actual byte transfer — you do this via shell. Construct a `curl` command using `method`, `url`, and each header from step 4. Example shape (substitute actual values): ``` curl -X PUT \ -H "<header-key>: <header-value>" \ -H "<header-key-2>: <header-value-2>" \ --data-binary @<local-file-path> \ "<upload-url>" ``` Run it with the workspace bash tool. Stream stdout/stderr to the user so they see the upload happening. A failed upload (non-2xx) means the URL expired or a header was wrong; regenerate via step 4. ### 6. Wait for processing Bitrise needs to validate the artifact (check signing, parse metadata) before it can be served from a public install page. Poll `get_installable_artifact_upload_and_processing_status`: - `connected_app_id` - `installable_artifact_id` Until the status indicates processed/ready (the exact field varies; treat "not failed and no longer pending" as ready). Reasonable cadence: every 5 seconds for the first minute, then every 15 seconds. If the response indicates a failure status, surface the message and stop — usually it's a signing issue with the artifact. ### 7. Confirm the public install page is on If you passed `with_public_page: true` at step 4, this should already be on. As a defensive check, call `set_installable_artifact_public_install_page`: - `connected_app_id` - `installable_artifact_id` - `with_public_page: true` This requires Project Admin / Workspace Admin / Project Owner role. The prospect's auto-created workspace makes them owner, so this should work, but the tool description warns that lower-role users get an error. If you hit that error, tell the user they don't have the role to enable public install pages and stop. ### 8. Get the URL and share it Call `list_installable_artifacts` filtered by `connected_app_id`. The response includes per-artifact metadata, including (typically) a public URL field. The exact field name isn't documented — read the response carefully and surface whatever URL field is there. Look for fields like `public_install_page_url`, `public_url`, `install_page_url`, or a nested object representing the public page. Show the user the URL with a one-liner about what they can do with it (open on a phone, send to testers, etc.). Note that iOS install pages need the device's UDID to be in a provisioning profile that signed the build — if the build is dev-signed, only registered devices can install. Mention this if the platform is iOS. If you cannot find a URL in the response, say so plainly: "I created the artifact and enabled the public page, but I can't find the URL in the API response. You can find it in the Bitrise web UI under Release Management → <app name> → Releases." Don't make one up. ### 9. (Optional) Add tester groups If the user wants to notify a group of testers rather than (or in addition to) sharing a public link: - `get_potential_testers` to see who's available in the workspace - `create_tester_group` with name + member slugs - `add_testers_to_tester_group` if more need to be added later - `notify_tester_group` to send the email Skip this entirely for the public-link-only flow. ## Things to watch out for - **Manual vs. store-connected apps.** For a prospect with no App Store / Play credentials yet, always pass `manual_connection: true` and `store_app_name`. Don't try to fetch credentials they don't have. - **The public install page URL is not documented.** Read the actual response from `list_installable_artifacts`. If you guess the field name and the SDK changes the shape, the user gets a 404 link. - **iOS install pages and UDIDs.** A development-signed IPA can only be installed on devices listed in the provisioning profile. For broader distribution, the user needs an enterprise distribution profile or Ad-Hoc with the right UDIDs. Surface this constraint when handing the link over for iOS. - **Don't paste PATs or signed URLs into chat.** The presigned upload URL contains a signature; treat it as short-lived secret. Use it once via shell, then drop it. - **`installable_artifact_id` is client-generated.** Don't reuse one across artifacts; each upload needs its own UUIDv4. - **Role check failures on the public-page enable call.** Tool description explicitly warns about this. If the user doesn't have the role, escalate to the workspace admin — don't try to retry.