--- title: "Create a new release" method: POST path: "/app/{appId}/release" tags: ["release"] --- # Create a new release `POST /app/{appId}/release` ## Request - Base URL: `https://api.runway.team` - URL: `https://api.runway.team/app/{appId}/release` - Auth: API key in header `X-API-Key` ## Path parameters - `appId` string, required ## Request body - CreateReleaseRequestBody: The `shouldCreateBranch`, `shouldBumpVersionOnBranch`, `base` and `commitsToCherryPick` properties apply only when `releaseType` is `hotfix`, and are ignored for other release types. - `version` string, required - `releaseType` 'release' | 'hotfix' | 'rollback', required: Release type used when creating or editing releases. - `targetKickoffDate` string, date-time: The target kickoff date for the release. All platforms. - `targetSubmitDate` string, date-time: The target submission date for the release. iOS and Android platforms only. - `targetReleaseDate` string, date-time: The target release date for the release. iOS platforms only. - `releasePilotId` string: The user id (email) of the release pilot for the release. Pass the string `'FROM_ROTATION'` to set the release pilot based on the pilot rotation schedule. - `releaseName` string: A user-friendly name for your release. - `shouldCreateBranch` boolean: Hotfixes only. Whether to immediately create the release branch, cut from the base release tag. Defaults to `false`. - `shouldBumpVersionOnBranch` boolean: Hotfixes only. Whether to bump the version on the newly created release branch. Requires `shouldCreateBranch` to be `true`. Defaults to `false`. - `base` CreateReleaseBaseTag: Hotfixes only. The release tag to branch the hotfix from. Defaults to the tag of the latest completed release. Must match an existing release tag on the app, otherwise the request is rejected. - `name` string, required: The name of the release tag, as returned by `GET /app/{appId}/releaseTags`. The version that tag marks is accepted here too, so both `v1.0.0` and `1.0.0` resolve to the same tag. - `commitsToCherryPick` string[]: Hotfixes only. The hashes of the commits to cherry-pick onto the release branch. Requires `shouldCreateBranch` to be `true`. ## Response `200` A release response - ReleaseEntity - `id` string, required: The id of the release entity - `version` string, required: The release version - `status` 'active' | 'completed' | 'canceled', required: The status of a release - `type` 'major' | 'minor' | 'point' | 'hotfix' | 'rollback', required: The type of release - `timelinePhase` 'upcoming' | 'current' | 'completed', required: The timeline phase of the release - `isReleaseTagged` boolean, required: Indicates whether the release has been tagged in VCS - `isKickedOff` boolean, required: Indicates whether the release has been kicked off in Runway - `isSubmitted` boolean, required: Indicates whether the release has been submitted for review in the app store - `isReleased` boolean, required: Indicates whether the release has been released to users. For iOS platforms, this corresponds to the App Store status being 'READY_FOR_SALE'. For Android platforms, this corresponds to the version's status being 'inProgress' or 'completed' - `createdAt` string, date-time, required: The date and time when the release was created in Runway - `releasePilotId` string: The release pilot for the release - `targetKickoffDate` string, date-time: The target kickoff date and time for the release - `targetSubmissionDate` string, date-time: The target submission date and time for the release - `targetReleaseDate` string, date-time: The target submission date and time for the release - `releaseBranch` string: The detected release branch for the release - `updatedAt` string, date-time: The date and time when the release was last updated in Runway - `kickedOffAt` string, date-time: The date and time when the release was kicked off in Runway - `submittedAt` string, date-time: The date and time when the a build for the release was submitted for review - `releasedAt` string, date-time: The date and time when a build for the release was made available to users. For iOS platforms, this corresponds to the App Store status being 'READY_FOR_SALE'. For Android platforms, this corresponds to the version's status being 'inProgress' or 'completed' - `rolloutCompletedAt` string, date-time: The date and time when the rollout completed for the release (phased release or staged rollout reaching 100%) - `completedAt` string, date-time: The date and time when the release was marked as completed in Runway. For iOS and Android platforms, this corresponds to the date on which a build was released to users based on the app store status. For other platforms, it corresponds to the date and time on which the production CI/CD workflow successfully completed for the first time. - `regressionTestingStatus` ReleaseRegressionTestingStatus - `status` string: The status of regression testing - `buildId` string: The id of the build that was tested - `buildHash` string: The build hash of the build that was tested, matching `buildHash` on the build entity - `updatedAt` string, date-time: The date and time when the status of regression testing was last updated - `releaseSummary` string: The automatically generated summary of the release. - `workItems` WorkItem[]: The work items associated with the release - `id` string, required: The id of the work item - `ticket` WorkItemTicket, required - `identifier` string, required: The identifier of the ticket - `description` string, required: The description of the ticket - `url` string, required: The url of the ticket - `owner` string, required: The owner of the ticket - `reporter` string, required: The reporter of the ticket - `status` string, required: The status of the ticket - `createdAt` string, date-time, required: The date and time the ticket was created - `updatedAt` string, date-time, required: The date and time the ticket was last updated - `isTicketDone` boolean, required: If the ticket is completed - `project` object, required: The project the ticket is associated with - `code` union, required: VCS item associated with work item - WorkItemCodeCommit - `identifier` string, required: The identifier of the commit - `codeStatus` 'openPR' | 'merged' | 'unmerged' | 'cherryPickPending' | 'cherryPickOpen' | 'cherryPickFailed' | 'cherryPickMerged', required: Status of WorkItemCode entity - `type` 'commit' | 'pullRequest', required: Type of WorkItemCode entity - `url` string, required: The url of the commit - `author` string, required: The author of the commit - `message` string, required: The message of the commit - `branch` string, required: The branch of the commit - `committedAt` string, date-time, required: The date and time the commit was created - `authoredAt` string, date-time, required: The date and time the commit was authored - WorkItemCodePullRequest - `identifier` string, required: The identifier of the pull request - `codeStatus` 'openPR' | 'merged' | 'unmerged' | 'cherryPickPending' | 'cherryPickOpen' | 'cherryPickFailed' | 'cherryPickMerged': Status of WorkItemCode entity - `type` 'commit' | 'pullRequest', required: Type of WorkItemCode entity - `url` string, required: The url of the pull request - `title` string, required: The title of the pull request - `description` string, required: The description of the pull request - `baseBranch` string, required: The base branch of the pull request - `headBranch` string, required: The head branch of the pull request - `author` string, required: The author of the pull request - `createdAt` string, date-time, required: The date and time the pull request was created - `updatedAt` string, date-time, required: The date and time the pull request was last updated - `pullRequestStatus` 'open' | 'merged' | 'closed' | 'unknown', required: Status of WorkItemCode entity - `explanationText` string, required: The detailed explanation of why this work item appears in this release - `ignored` boolean, required: If the work item has been marked as ignored - `isItemDone` boolean, required: If the work item is completed - `steps` ReleaseStepEntity[], required: The steps of the release - `stepId` unknown - `type` 'kickoff' | 'featureReadiness' | 'releaseCandidate' | 'regressionTesting' | 'betaTesting' | 'metadata' | 'screenshots' | 'approvals' | 'submission' | 'storeReview' | 'takeoff' | 'ciDistribution', required: The type of release step - `displayName` string, required: The display name of the step - `status` 'ready' | 'pending' | 'pendingChecklist' | 'blocked' | 'inactive', required: The status of a release step - `statusReasonString` string, required: The user-friendly description of the reason for the status of the step - `data` union - object - `approvalItems` ChecklistItemEntity[], required: The list of approval items for the release step. This object is only returned for release steps of type `approval` - `id` string, required: The identifier of the checklist item - `title` string, required: The title of the checklist item - `description` string: The description of the checklist item. Accepts markdown. - `approverGroups` UserGroup[], required: The list of user groups that can approve this checklist item. Custom groups can be included as well. - `releaseType` 'all' | 'hotfixOnly' | 'rollbackOnly' | 'allExceptHotfix', required: The type of release this checklist item will appear on - `notifyEnabled` boolean, required: Whether the checklist item will notify on Slack when its status changes - `statuses` ChecklistItemStatusType[], required: The list of possible checklist item status types for this checklist item. A subset of all possible ChecklistItemStatusType values - `releaseStepType` string: The release step that the checklist item appears on. Will be `null` if the placement of the item is not `binary`. Can either be of type ReleaseStepType, or a step's Step ID can be sent instead - `stepId` unknown - `oneOffForVersion` string: If the checklist item only applies for a single release version, this field will contain the version string for that version - `status` ChecklistItemStatus: The status of a checklist item - `status` 'approved' | 'rejected' | 'inProgress' | 'blocked' | 'passed' | 'failed', required: All possible statuses for a checklist item - `createdBy` string, required: The userId (email) of the user that created the checklist item - `createdAt` string, date-time, required: The date and time the checklist item was created - `placement` 'stepChecklist' | 'approvals' | 'regressionTesting', required: The placement of a given checklist item - `comment` ChecklistItemComment: A comment on a checklist item - `createdAt` string, date-time - `createdBy` string: The user id (email) of the user that added the comment - `comment` string: The comment string. Can be markdown. - object - `regressionItems` ChecklistItemEntity[], required: The list of regression items for the release step. This object is only returned for release steps of type `regressionTesting` - `id` string, required: The identifier of the checklist item - `title` string, required: The title of the checklist item - `description` string: The description of the checklist item. Accepts markdown. - `approverGroups` UserGroup[], required: The list of user groups that can approve this checklist item. Custom groups can be included as well. - `releaseType` 'all' | 'hotfixOnly' | 'rollbackOnly' | 'allExceptHotfix', required: The type of release this checklist item will appear on - `notifyEnabled` boolean, required: Whether the checklist item will notify on Slack when its status changes - `statuses` ChecklistItemStatusType[], required: The list of possible checklist item status types for this checklist item. A subset of all possible ChecklistItemStatusType values - `releaseStepType` string: The release step that the checklist item appears on. Will be `null` if the placement of the item is not `binary`. Can either be of type ReleaseStepType, or a step's Step ID can be sent instead - `stepId` unknown - `oneOffForVersion` string: If the checklist item only applies for a single release version, this field will contain the version string for that version - `status` ChecklistItemStatus: The status of a checklist item - `status` 'approved' | 'rejected' | 'inProgress' | 'blocked' | 'passed' | 'failed', required: All possible statuses for a checklist item - `createdBy` string, required: The userId (email) of the user that created the checklist item - `createdAt` string, date-time, required: The date and time the checklist item was created - `placement` 'stepChecklist' | 'approvals' | 'regressionTesting', required: The placement of a given checklist item - `comment` ChecklistItemComment: A comment on a checklist item - `createdAt` string, date-time - `createdBy` string: The user id (email) of the user that added the comment - `comment` string: The comment string. Can be markdown. - `testRuns` RegressionTestingTestRunEntity[], required: The list of regression testing test runs from the connected integration associated with this release step. This object is only returned for release steps of type `regressionTesting`. - `id` string, required: The id of the test run. - `name` string, required: The name of the test run. - `description` string, required: The description of the test run. - `statuses` RegressionTestingTestRunStatusEntity[], required: Per-status breakdown of the test cases in the test run. - `displayableName` string, required: The human-readable name of the status (e.g. `Passed`, `Failed`, `Blocked`). - `testCasesCount` integer, required: The number of test cases in this status. - `progressFraction` number, float, required: The fraction (0.0 - 1.0) of test cases in the test run that are in this status. - `completedAt` string, date-time, nullable, required: The date and time when the test run was completed. Null if the test run is still in progress. - `completionFraction` number, float, required: The fraction (0.0 - 1.0) of test cases in the test run that have been completed. - `externalUrl` string, required: The URL to the test run in the external test management integration. - `createdAt` string, date-time, required: The date and time when the test run was created. - `updatedAt` string, date-time, nullable, required: The date and time when the test run was last updated. - object - `items` FeatureReadinessItemEntity[], required: The list of Feature Readiness work items for the release. This object is only returned for release steps of type `featureReadiness`. - `id` string: The unique identifier for the item. Pass this value as `frItemId` when calling the ignore/un-ignore endpoint. - `ticket` object, nullable: The ticket associated with this item, if any. - `identifier` string - `description` string - `url` string - `owner` string, nullable - `reporter` string, nullable - `status` string - `isTicketDone` boolean - `priority` string, nullable - `ticketType` string, nullable - `code` union: The code associated with this item: either a pull request (PR / code review) or a commit (or null if none). This is the canonical location of pull request / code review information on a release — query the `featureReadiness` step to retrieve PR data. - WorkItemCodePullRequest - … - WorkItemCodeCommit - … - `explanationText` string, nullable: Optional explanation for the item. - `ignored` boolean: Whether the item has been ignored. Ignored items no longer block the release from being considered ready. - `autoIgnored` boolean: Whether the item would be ignored automatically based on app settings. - `isItemDone` boolean: True when both the code is merged and the ticket is done. - `debugVariant` string: Identifies which variation of feature item this is (used to indicate the source of the work item). - object - `releasedAt` string, date-time, nullable: The date and time when the release was released to users. - `rolloutStartedAt` string, date-time, nullable: The date and time when the phased/staged rollout started for the release. - `releaseAdoptionRates` object, nullable: The current adoption rates for the release (fraction of users on this version) keyed by stability monitoring integration installation ID, if available. - `phasedRelease` PhasedReleaseData: Phased/staged rollout details for a release. Applicable to both Apple (phased release) and Google (staged rollout). - `state` string: The phased release state (e.g. Apple: ACTIVE, PAUSED, COMPLETE; Google: inProgress, halted, completed). - `dayNumber` integer: The current phased release day (Apple only, 1-7). 0 if not applicable. - `startDate` string, date-time, nullable: The date the phased/staged rollout started. - `userFraction` number, float: The fraction of users receiving the update (0.0 to 1.0). For Apple this is derived from the day number; for Google this is the configured staged rollout percentage. - `appStoreReviewData` AppStoreReviewDataEntity: Aggregated App Store reviews data for a rollout step run. - `averageRating` number, float, required: The average rating of the app on the App Store at the time the data was captured. - `totalRatingsCount` integer, required: The total number of ratings for the app on the App Store at the time the data was captured. - `userReviewIssues` AppStoreReviewsIssueEntity[], required: Issues surfaced from user reviews for the release. - `description` string, required: Human-readable description of the issue. - `isNewIssue` boolean, required: Whether this issue is new in the current release (i.e. not seen in prior releases). - `reviewExamples` AppStoreReviewEntity[], required: Example user reviews that contributed to this issue. - … - `monitoringStatistics` MonitoringStatisticEntity[]: Monitoring statistics for the rollout, including crash-free rates, adoption, and custom metrics. Each entry contains the current summary value (no time series data). - `type` string: The metric type (e.g. 'userStability' for crash-free users, 'sessionStability' for crash-free sessions, 'adoptionRate', 'eventsPerActiveUser', etc.). - `integrationType` string: The integration providing this metric (e.g. 'firebase_crashlytics', 'bugsnag', 'datadog'). - `currentValue` number, float, nullable: The current value of the metric for this release version. - `delta` number, float, nullable: The change in the metric value compared to the previous version. - `previousVersion` string, nullable: The previous release version used for comparison. - `previousValue` number, float, nullable: The metric value for the previous release version. - `monitoringMetricStatus` 'healthy' | 'unhealthy' | 'null', nullable: The health status of this metric, if a threshold is configured. - object: The release's submission, review and release timestamps for the Release (`takeoff`) step, plus the precomputed review durations. `startedReviewAt` is Apple-only, so both durations are null on Google Play. - `submittedAt` string, date-time, nullable: The date and time when the release was submitted to the app store for review. - `startedReviewAt` string, date-time, nullable: The date and time when the app store started reviewing the release. Not set by Google Play. - `approvedAt` string, date-time, nullable: The date and time when the app store approved the release. - `markedRejectedAt` string, date-time, nullable: The date and time when the release was marked as rejected in Runway. - `releasedAt` string, date-time, nullable: The date and time when the release was released to users. - `waitingForReviewSeconds` number, double, nullable: How long the release sat queued before the app store started reviewing it, in seconds (`startedReviewAt - submittedAt`). - `timeInReviewSeconds` number, double, nullable: How long the release was under app store review, in seconds (`approvedAt - startedReviewAt`). - `checklistItems` ChecklistItemEntity[], required: The list of checklist items for the release step - `id` string, required: The identifier of the checklist item - `title` string, required: The title of the checklist item - `description` string: The description of the checklist item. Accepts markdown. - `approverGroups` UserGroup[], required: The list of user groups that can approve this checklist item. Custom groups can be included as well. - `releaseType` 'all' | 'hotfixOnly' | 'rollbackOnly' | 'allExceptHotfix', required: The type of release this checklist item will appear on - `notifyEnabled` boolean, required: Whether the checklist item will notify on Slack when its status changes - `statuses` ChecklistItemStatusType[], required: The list of possible checklist item status types for this checklist item. A subset of all possible ChecklistItemStatusType values - `releaseStepType` string: The release step that the checklist item appears on. Will be `null` if the placement of the item is not `binary`. Can either be of type ReleaseStepType, or a step's Step ID can be sent instead - `stepId` unknown - `oneOffForVersion` string: If the checklist item only applies for a single release version, this field will contain the version string for that version - `status` ChecklistItemStatus: The status of a checklist item - `status` 'approved' | 'rejected' | 'inProgress' | 'blocked' | 'passed' | 'failed', required: All possible statuses for a checklist item - `createdBy` string, required: The userId (email) of the user that created the checklist item - `createdAt` string, date-time, required: The date and time the checklist item was created - `placement` 'stepChecklist' | 'approvals' | 'regressionTesting', required: The placement of a given checklist item - `comment` ChecklistItemComment: A comment on a checklist item - `createdAt` string, date-time - `createdBy` string: The user id (email) of the user that added the comment - `comment` string: The comment string. Can be markdown. - `appStoreData` union - object - `type` 'AppleAppStoreData' | 'GooglePlayStoreData', required: The type of app store data - `releaseType` string, required: The release type in ASC for the release - `earliestReleaseDate` string, date-time: the earliest release date that the update will be released on, set if the release type is `SCHEDULED`. If the update is approved before the earliest release date, it will be released automatically on the `earliestReleaseDate` - `state` string, required: The ASC state of the release, can be one of a number of [version states](https://developer.apple.com/documentation/appstoreconnectapi/appstoreversionstate) defined by Apple. - `phasedRelease` ApplePhasedRelease: The phased release details for a given version release - `state` string, required: The phased release state for the update, can be one of a number of [phased release states](https://developer.apple.com/documentation/appstoreconnectapi/phasedreleasestate) defined by Apple - `dayNumber` number, required: The phased release day - `startDate` string, date-time: The date the phased release began - object - `type` 'AppleAppStoreData' | 'GooglePlayStoreData', required: The type of app store data - `state` string, required: The Google Play Developer API status of the versioned release, can be one of a number of [release statuses](https://developers.google.com/android-publisher/api-ref/rest/v3/edits.tracks#Status) - `phasedRelease` GoogleStagedRollout: The staged rollout details for a versioned Android release - `state` string, required: The Google Play Developer API status of the versioned release, can be one of a number of [release statuses](https://developers.google.com/android-publisher/api-ref/rest/v3/edits.tracks#Status) - `userFraction` number - `customMetadata` CustomMetadata: Custom metadata attached to the release, keyed by a stable id derived from each entry's title. Each value is an entry with a human-readable `title` and a `value` that may be any JSON type. ## Other responses - `400`: Bad request response - `404`: Resource not found response --- [API](https://skmtc.dev/runway/apis/runway-rest-api.md) - [All operations](https://skmtc.dev/runway/apis/runway-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runway/apis/runway-rest-api/revisions/081109863a9a?raw)