App configuration files

Although adding and configuring apps in Runway can primarily be accomplished via the Runway web app, it's also now possible for teams to accomplish this programmatically through Runway’s public API using YAML configuration files.

Fetching an existing app's configuration file

You can access the configuration file of any of your existing apps in Runway by using the GET /app/{appId}/config endpoint in Runway's public API. The resulting YAML file will contain your app's current configuration details, which can be a good starting point if you want to programmatically create new apps in Runway with similar configurations.

Adding an app using a YAML configuration file

You can add an app to your Runway organization programmatically by calling the POST /app/config endpoint in Runway's public API with a .yml configuration file in the request body.

The configuration file must include the required properties for successful app creation. See below for a sample configuration file in YAML syntax.

Required properties for app creation are:

• name

• platform

Properties that are not required will either be left empty or be populated with default values by Runway if not specified.

# App example
# Describes an App within Runway
---
name: Apollo
platform: ios
appGroup: 'Apollo'
icon: 'https://uploads-ssl.webflow.com/5edfa38a1bd219267bdf69b7/5fadc479febc556d17ade92e_nasa-org.png'
integrations:
    'GitHub Apollo': # The ID or alias of an integration
        type: 'github-vcs' # For available integration types, see https://api-docs.runway.team/#tag/IntegrationType
        provider: 'Apple GH' # Matches on either ID or alias
        data:
            repoName: 'apollo-ios' # The payload used to configure the integration. Dependent on integration type. For examples, compare to a payload from the GET app config endpoint.
    'App Store Apollo':
        type: 'apple'
        provider: 'Apple App Store'
        data:
            bundleId: 'com.nasa.apollo'
    'Build system Apollo':
        type: 'github-ci'
        provider: 'github:111222333' # example of a provider ID
        data:
            workflowId: 'demo-ios/deploy'
            devWorkflowId: 'demo-ios/build'
    'Testrail Apollo':
        type: 'testrail'
        provider: 'Testrail'
        data:
            testRunNameKeywords: 'iOS'
            project: 'Demo Testrail iOS'
    'JIRA Apollo':
        type: 'jira'
        provider: 'JIRA'
        data:
            projects: ['Demo', 'Demo-Core']
            additionalDoneStatuses: ['Done', 'Deployed', 'Ready to Release']
    'Beta testing Apollo':
        type: 'apple-beta'
        provider: 'Apple App Store'
        data:
            bundleId: 'com.nasa.apollo'
    'Slack Apollo':
        type: 'slack'
        provider: 'Slack'
        data:
            primaryChannelIds: ['#apollo-releases']
    'Sentry Apollo':
        type: 'sentry'
        provider: 'Sentry'
        data:
            orgId: 'NASA'
            projectId: 'Apollo iOS'
            prodEnvironmentIdentifier: 'production'
            betaEnvironmentIdentifier: 'beta'
    'Amplitude Apollo':
        type: 'amplitude'
        provider: 'amplitude'
        data:
            selectedEventsAndParams:
                - eventName: 'add to cart'
                - eventName: 'view checkout'
                  paramName: 'amount'
                - eventName: 'view checkout'
                  paramName: 'itemCount'
    'Optimizely Apollo':
        provider: 'Optimizely'
        data:
            projectId: 'Apollo'
            environmentId: 'Production'
            versionAttributeName: 'app_version'
    'PagerDuty Apollo':
        type: 'pagerduty-scheduling'
        provider: 'PagerDuty'
        data:
            scheduleId: 'Apollo Release Rotation'
    'Crowdin Apollo':
        type: 'crowdin'
        provider: 'Crowdin'
        data:
            projectId: 'Apollo'
            metadataProjectId: 'Apollo Metadata'
buildDistro:
    buckets:
        'Release Candidates': # bucket name
            type: 'rc' # For available bucket types, see https://api-docs.runway.team/#tag/BucketType
            orgWideAccessEnabled: true
            notificationsEnabled: true
            members:
                'Release pilot': 'tester'
                'PMs': 'tester'
                'EMs': 'admin'
            rules:
                - branch: 'release-{version}'
                  type: 'Branch' # can be 'Branch' or 'PR'
                  workflow: 'build-rc'
                  fileFilterPatterns:
                      - '{*}.ipa'
        'Development':
            type: 'dev'
            notificationsEnabled: true
            members: # group or user to permission level
                'Release pilot': 'tester' # permission level can be 'admin', 'uploader', or 'tester'
                'PMs': 'tester'
                'QA': 'tester'
                'EMs': 'admin'
            rules:
                - baseBranch: 'main'
                  type: 'PR'
                  workflow: 'demo-ios/build'
                  fileFilterPatterns:
                      - '{*}.ipa'
appSettings:
    defaultReleaseType: 'minor' # can be any non-hotfix type: https://api-docs.runway.team/#tag/ReleaseType
    assumeHotfixesArePointReleases: false
    versionFiles:
        - 'appollo.xcodeproj/project.pbxproj'
        - 'appollo/settings.xcconfig'
    localizationDirectories:
        - 'appollo/resources'
    requireFixApprovals: false
    enableFixStatusChecks: false # can only be true if requireFixApprovals is true
    hideNotRequiredReleaseStepsInTimeline: false
    appUsers:
        - [e-mail]
        - [e-mail]
        - [e-mail]
        - [e-mail]
    branchSettings:
      'GitHub Apollo': # must match a VCS integration specified in the integrations section
            releaseBranchPatterns:
              all:
                pattern: 'release-{version}'
              hotfix:
                pattern: 'hotfix-{version}'
            workingBranch: main
    tagSettings:
        tagSettingsMain:
            pattern: '{version}'
    featureAffiliations:
        FA Fix Versions:
            integration: 'Jira Apollo' # must match an issue tracking integration ID or alias
            type: 'fixVersion'
            pattern: '{version}'
    appStoreReleaseSettings:
        releaseMethod: manual
        phasedReleaseEnabled: true
stepGroups: # all steps for the app, arranged in groups
    - steps:
          - name: Kickoff
            archetype: 'kickoff' # type of the step. For valid types, see https://api-docs.runway.team/#tag/ReleaseStepType
            releaseTypes: # the release types for this step. Can be 'standard', 'hotfix', or 'rollback'
              standard:
                required: true # whether this step is required for the given release type
              hotfix:
                required: true
          - name: 'Feature readiness'
            archetype: 'featureReadiness'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
          - name: Translations
            archetype: 'translations'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
          - name: 'Rollback build'
            archetype: 'rollbackBuild' # The special 'rollbackBuild' step is only valid for the 'rollback' release type
            releaseTypes:
              rollback:
                required: true
    - steps:
          - name: Release candidate
            archetype: 'releaseCandidate'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: true
          - name: Regression testing
            archetype: 'regressionTesting'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
          - name: Beta testing
            archetype: 'betaTesting'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
    - steps:
          - name: Screenshots
            archetype: 'screenshots'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
              rollback:
                required: true
          - name: Metadata
            archetype: 'metadata'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: false
              rollback:
                required: true
    - steps:
          - name: Approvals
            archetype: 'approvals'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: true
              rollback:
                required: true
    - steps:
          - name: Submit
            archetype: 'submission'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: true
              rollback:
                required: true
          - name: Review
            archetype: 'storeReview'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: true
              rollback:
                required: true
          - name: Release
            archetype: 'takeoff'
            releaseTypes:
              standard:
                required: true
              hotfix:
                required: true
              rollback:
                required: true

Not all properties of your app in Runway are currently configurable programatically. If you wish to configure a property that's not supported via programatic configuration, you must use the web UI.

Integrations can only be configured programmatically if they're using an existing integration provider. If you need to authenticate with a new integration provider, you must do so using the Runway web UI.