fastlane-plugin-saucelabs_appdist 0.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 927d1fffc84a5b5d631561c209913bade18095f39a5d9b383124ecd0e29b2228
-  data.tar.gz: 87aaa2dcae9f1f4d5002d757b55d68a6932212a445427497e5154789fac9fdcd
+  metadata.gz: 69bb3f94b51fc03eba9edc8cbd584119f403ff7e65fb5cb81d7817c8e397ed2c
+  data.tar.gz: 1afe02dd17556b0973e1f039e885610c8e8554fcae1ab5a592ebbfc2cc5f987e
 SHA512:
-  metadata.gz: d812d6cb9784e61b80dd04eed593c947aefe365438336472dee5680888fb4b8584fe57d1f88041fef1792bbb4deee2b2c616dbed6fba6d25da31acad56e42f79
-  data.tar.gz: 68a2aa00bc80d941f9fabee37d2231d1e7e5cd71fe348b06dbe0808fb3e59ef34e5b91ff17de5ee0025056d3ad6d3433fc93d2ce0b9405f986ec8618face7856
+  metadata.gz: ab43059f2b0c361acc749afd6eda3793dab3da115388ce8a4075755788f5fbf35f6db7e0cff4d092a36b8ff2e3386833d5045cce0b9abf57b7f3ec11e27c8515
+  data.tar.gz: c6abcf359b775938a2ece9b150e7b986467b9dfcc86adadbb51a4e17cced715b678f57dd924f46c6fe575a0826f78eecd101f72d5e03e5ac8643f81843cbebb4

data/README.md

@@ -29,6 +29,23 @@ saucelabs_appdist(
 )
 ```
 
+### Uploading to the same app every time
+
+Mobile App Distribution matches an upload to an existing app by its bundle id, within the teams you can write to. When the same bundle id lives on more than one of your teams, the upload cannot tell them apart and is refused with code `136`. Pass `team_id` to say which team owns the app:
+
+```ruby
+saucelabs_appdist(
+  api_key: "your_api_key",
+  ipa: "./path/to/app.ipa",
+  team_id: 42,
+  landing_page_slug: "my-app-beta"
+)
+```
+
+Every upload then appends a build to the same app, and `/install/my-app-beta` always serves the latest one. Re-sending the same `landing_page_slug` on every upload is safe — an app may keep claiming its own slug.
+
+`folder_name` takes part in the match as well: an upload finds an existing app only when the folder matches what that app already has, and an upload that sends no folder looks only among apps that have none. So send the same `folder_name` on every upload, or none at all — changing it mid-pipeline routes the next build to a different app.
+
 ## Parameters
 
 | Key | Description | Default |
@@ -38,19 +55,41 @@ saucelabs_appdist(
 | `apk` | Path to your APK file (Android) | — |
 | `symbols_file` | Symbols mapping file | — |
 | `upload_url` | API URL for App Distribution | `https://app.testfairy.com` |
-| `testers_groups` | Array of tester groups | `[]` |
-| `metrics` | Array of metrics to record | `[]` |
+| `api_version` | Upload transport. `:v3` arrives in plugin 3.x | `:legacy` |
+| `team_id` | Team that owns the app. Required when a bundle id exists on several of your teams | `""` |
 | `comment` | Additional release notes | `No comment provided` |
-| `auto_update` | Auto-upgrade users (`on`/`off`) | `off` |
-| `notify` | Send email to testers (`on`/`off`) | `off` |
-| `options` | Array of options | `[]` |
-| `custom` | Custom options string | `""` |
-| `timeout` | Request timeout in seconds | — |
+| `notify` | Send email to testers (`on`/`off`/`1`/`0`) | `off` |
 | `tags` | Custom tags for builds | `[]` |
+| `metadata` | Key-value pairs stored on the build, returned under `metadata` | `{}` |
 | `folder_name` | Dashboard folder name | `""` |
 | `landing_page_mode` | Landing page visibility (`open`/`closed`) | `open` |
-| `upload_to_saucelabs` | Upload to Sauce Labs (`on`/`off`) | `off` |
-| `platform` | Platform override | `""` |
+| `landing_page_slug` | Custom URL token for the landing page, served at `/install/<slug>` | `""` |
+| `community_token` | Legacy name for `landing_page_slug` | `""` |
+| `sync_to_saucelabs` | Also upload the file to Sauce Labs app storage (`on`/`off`) | `off` |
+| `platform` | Platform of a generic upload. Ignored for `.ipa`, `.apk` and `.aab` | `""` |
+| `timeout` | Request timeout in seconds | — |
+
+### Legacy TestFairy parameters
+
+Mobile App Distribution ignores the parameters below. Private-cloud instances still running legacy TestFairy honor them, so the plugin keeps sending them and warns when you set one.
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `testers_groups` | Tester groups to notify. App Distribution notifies every tester on the project | `[]` |
+| `app_description` | Landing page description. Set it from the App Distribution dashboard instead | `""` |
+| `metrics` | Session metrics recorded by the TestFairy SDK | `[]` |
+| `options` | Session options for the TestFairy SDK | `[]` |
+| `custom` | Custom options string | `""` |
+| `auto_update` | Auto-upgrade users (`on`/`off`) | `off` |
+| `upload_to_saucelabs` | Deprecated. Renamed to `sync_to_saucelabs` | `off` |
+
+## Upgrading from 0.3.x
+
+Your Fastfile keeps working. Three things change:
+
+1. **`upload_to_saucelabs` is deprecated.** Mobile App Distribution reads the field as `sync_to_saucelabs`, so the old name uploaded nothing. Rename it; the plugin warns until you do and sends both field names in the meantime.
+2. **Parameters App Distribution ignores now warn** instead of returning `status: ok` as though they applied. See the table above.
+3. **A failed upload raises the API's own error.** `UI.user_error!` carries the `code` and `message`, and the full envelope lands in `lane_context`.
 
 ## Response
 
@@ -75,15 +114,48 @@ Example response:
   "app_url": "https://app.testfairy.com/download/.../getapp",
   "invite_testers_url": "https://app.testfairy.com/projects/1/builds/1/invite",
   "icon_url": "https://app.testfairy.com/icons/.../icon.png",
-  "options": "video-quality=medium,screenshot-interval=1,session-length=60m,video,logcat,shake,cpu,memory,phone-signal,battery,wifi",
+  "options": "",
   "platform": "iOS",
   "tags": [],
-  "metadata": [],
-  "has_testfairy_sdk": true,
+  "metadata": {},
+  "has_testfairy_sdk": false,
   "symbols_download_url": null,
   "attachments": null,
-  "landing_page_url": "https://app.testfairy.com/join/xxxxxx",
-  "build_specific_landing_page_url": "https://app.testfairy.com/join/xxxxxx?id=1",
-  "landing_page_mode": "closed"
+  "landing_page_url": "https://app.testfairy.com/install/xxxxxx",
+  "build_specific_landing_page_url": "https://app.testfairy.com/install/0123456789abcdef0123456789abcdef",
+  "landing_page_mode": "closed",
+  "community_token": "xxxxxx",
+  "app_description": ""
 }
 ```
+
+## Errors
+
+A failed upload raises a `FastlaneError` naming the API's own code and message, for example:
+
+```
+Sauce Labs App Distribution upload failed with code 136: Invalid team_id.
+```
+
+The full error envelope stays in `lane_context` so a lane can decide whether to retry:
+
+```ruby
+begin
+  saucelabs_appdist(api_key: "...", ipa: "./app.ipa")
+rescue FastlaneCore::Interface::FastlaneError
+  error = lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_ERROR]
+  UI.message("code #{error['code']}: #{error['message']}")
+  raise
+end
+```
+
+Codes you are most likely to meet:
+
+| Code | Meaning |
+|------|---------|
+| `5` | Invalid API key |
+| `121` | File type not accepted |
+| `124` | `landing_page_slug` is malformed |
+| `125` | `landing_page_slug` already belongs to another app |
+| `135` | `landing_page_mode` is neither `open` nor `closed` |
+| `136` | The bundle id exists on several of your teams — pass `team_id` |

data/lib/fastlane/plugin/saucelabs_appdist/actions/saucelabs_appdist_action.rb

@@ -2,9 +2,37 @@ module Fastlane
   module Actions
     module SharedValues
       SAUCELABS_APPDIST_UPLOAD_RESPONSE = :SAUCELABS_APPDIST_UPLOAD_RESPONSE
+      SAUCELABS_APPDIST_UPLOAD_ERROR = :SAUCELABS_APPDIST_UPLOAD_ERROR
     end
 
     class SaucelabsAppdistAction < Action
+      # Config that stays on this side of the wire.
+      LOCAL_ONLY_PARAMS = %i[upload_url timeout api_version].freeze
+
+      # Params whose lane name is also the upload field name.
+      PASSTHROUGH_PARAMS = %i[
+        api_key ipa apk symbols_file comment notify custom platform
+        folder_name landing_page_mode app_description
+      ].freeze
+
+      # Params resolved as a pair or expanded into several fields.
+      RECONCILED_PARAMS = %i[
+        community_token landing_page_slug upload_to_saucelabs sync_to_saucelabs metadata
+      ].freeze
+
+      # Mobile App Distribution ignores these. Legacy TestFairy servers still
+      # read them, so they stay on the wire and only warn.
+      IGNORED_BY_APPDIST = {
+        testers_groups: 'Mobile App Distribution notifies every tester on the project; per-group notify is not available yet.',
+        app_description: 'Set the landing page description from the dashboard.',
+        metrics: 'Session metrics came from the TestFairy SDK, which Mobile App Distribution does not ship.',
+        options: 'Session options came from the TestFairy SDK, which Mobile App Distribution does not ship.',
+        custom: 'No equivalent.',
+        auto_update: 'No equivalent.'
+      }.freeze
+
+      BINARY_EXTENSIONS = %w(.ipa .apk .aab).freeze
+
       def self.upload_build(upload_url, ipa, options, timeout)
         require 'faraday'
         require 'faraday_middleware'
@@ -41,98 +69,190 @@ module Fastlane
       def self.run(params)
         UI.success('Starting with ipa upload to Sauce Labs App Distribution...')
 
-        metrics_to_client = lambda do |metrics|
-          metrics.map do |metric|
-            case metric
-            when :cpu, :memory, :network, :gps, :battery, :mic, :wifi
-              metric.to_s
-            when :phone_signal
-              'phone-signal'
-            else
-              UI.user_error!("Unknown metric: #{metric}")
-            end
-          end
-        end
+        path = params[:ipa] || params[:apk]
+        UI.user_error!("No ipa or apk were given") unless path
 
-        options_to_client = lambda do |options|
-          options.map do |option|
-            case option.to_sym
-            when :shake, :anonymous
-              option.to_s
-            when :video_only_wifi
-              'video-only-wifi'
-            else
-              UI.user_error!("Unknown option: #{option}")
-            end
-          end
-        end
+        # One snapshot, taken before `params.values` back-fills defaults into
+        # the same hash it reads from.
+        given = provided_keys(params)
+        warn_ignored_params(params, given)
+        client_options = self.client_options(params, given)
+
+        return path if Helper.test?
+
+        response = self.upload_build(params[:upload_url], path, client_options, params[:timeout])
+        UI.user_error!(upload_error_message(response)) unless parse_response(response)
+
+        UI.success("Build successfully uploaded to Sauce Labs App Distribution.")
+        UI.success("Response:\n#{JSON.pretty_generate(Actions.lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_RESPONSE])}")
+      end
+
+      # Build the upload fields. Every declared option is either mapped here or
+      # named in LOCAL_ONLY_PARAMS — an option added without a mapping fails
+      # loud instead of vanishing.
+      def self.client_options(params, given = provided_keys(params))
+        options = {}
+
+        params.values.each_key do |key|
+          value = params[key]
 
-        # Rejecting key `upload_url` and `timeout` as we don't need it in options
-        client_options = Hash[params.values.reject do |key, value|
-          [:upload_url, :timeout].include?(key)
-        end.map do |key, value|
           case key
-          when :api_key
-            [key, value]
-          when :ipa
-            [key, value]
-          when :apk
-            [key, value]
-          when :symbols_file
-            [key, value]
-          when :testers_groups
-            [key, value.join(',')]
+          when *LOCAL_ONLY_PARAMS, *RECONCILED_PARAMS
+            next
+          when *PASSTHROUGH_PARAMS
+            options[key] = value
+          when :team_id
+            # 0.3.2 sent no team_id field at all, so don't start sending an
+            # empty one: a server reading its presence as "filter by team"
+            # would reject an upload that used to work.
+            options[key] = value.to_s unless value.to_s.empty?
+          when :testers_groups, :tags
+            options[key] = Array(value).join(',')
           when :metrics
-            [key, metrics_to_client.call(value).join(',')]
-          when :comment
-            [key, value]
-          when :auto_update
-            ['auto-update', value]
-          when :notify
-            [key, value]
+            options[key] = metrics_to_client(value).join(',')
           when :options
-            [key, options_to_client.call(value).join(',')]
-          when :custom
-            [key, value]
-          when :tags
-            [key, value.join(',')]
-          when :folder_name
-            [key, value]
-          when :landing_page_mode
-            [key, value]
-          when :upload_to_saucelabs
-            [key, value]
-          when :platform
-            [key, value]
+            options[key] = options_to_client(value).join(',')
+          when :auto_update
+            options['auto-update'] = value
           else
             UI.user_error!("Unknown parameter: #{key}")
           end
-        end]
+        end
+
+        slug = landing_page_slug(params, given)
+        options[:community_token] = slug
+        options[:landing_page_slug] = slug
 
+        sync = sync_to_saucelabs(params, given)
+        options[:upload_to_saucelabs] = sync
+        options[:sync_to_saucelabs] = sync
+
+        options.merge(metadata_fields(params[:metadata]))
+      end
+
+      # `upload_to_saucelabs` is the legacy field name; Mobile App Distribution
+      # reads `sync_to_saucelabs`. Both go out so one lane works on either.
+      def self.sync_to_saucelabs(params, given = provided_keys(params))
+        legacy = provided?(params, :upload_to_saucelabs, given) ? params[:upload_to_saucelabs] : nil
+        current = provided?(params, :sync_to_saucelabs, given) ? params[:sync_to_saucelabs] : nil
+
+        if legacy && current && legacy != current
+          UI.user_error!("`upload_to_saucelabs: '#{legacy}'` contradicts `sync_to_saucelabs: '#{current}'`. Keep `sync_to_saucelabs`.")
+        end
+
+        UI.important("`upload_to_saucelabs` is deprecated — rename it to `sync_to_saucelabs`.") if legacy
+
+        current || legacy || params[:sync_to_saucelabs]
+      end
+
+      # `community_token` is the legacy name for `landing_page_slug`.
+      def self.landing_page_slug(params, given = provided_keys(params))
+        legacy = provided?(params, :community_token, given) ? params[:community_token] : nil
+        current = provided?(params, :landing_page_slug, given) ? params[:landing_page_slug] : nil
+
+        if legacy && current && legacy != current
+          UI.user_error!("`community_token: '#{legacy}'` contradicts `landing_page_slug: '#{current}'`. Pass one of them.")
+        end
+
+        current || legacy || ''
+      end
+
+      # Mobile App Distribution folds every `metadata_<key>` field into the
+      # build's metadata, so one hash entry becomes one field.
+      def self.metadata_fields(metadata)
+        (metadata || {}).each_with_object({}) do |(key, value), fields|
+          name = key.to_s.strip
+          UI.user_error!("Metadata keys cannot be empty") if name.empty?
+
+          fields["metadata_#{name}"] = value.to_s
+        end
+      end
+
+      def self.warn_ignored_params(params, given = provided_keys(params))
+        IGNORED_BY_APPDIST.each do |key, alternative|
+          next unless provided?(params, key, given)
+
+          UI.important("Sauce Labs Mobile App Distribution ignores `#{key}`. #{alternative} Legacy TestFairy servers still honor it.")
+        end
+
+        return unless provided?(params, :platform, given) && binary_upload?(params)
+
+        UI.important('Sauce Labs Mobile App Distribution ignores `platform` for .ipa, .apk and .aab uploads — it reads the platform from the binary. The param applies to generic uploads only.')
+      end
+
+      # Keys the caller supplied, by lane argument or by env var.
+      #
+      # Two channels, read separately on purpose. `_values` holds ONLY
+      # lane-passed values and must be read before `params.values` back-fills
+      # defaults into that same hash. Env values never enter `_values` at all —
+      # fastlane consults them later, inside `fetch` — so asking only `_values`
+      # makes every FL_SAUCELABS_APPDIST_* value read as absent.
+      def self.provided_keys(params)
+        available_options.select do |option|
+          params._values.key?(option.key) || !option.fetch_env_value.nil?
+        end.map(&:key)
+      end
+
+      # True when the lane passed the param and gave it a real value.
+      def self.provided?(params, key, given = provided_keys(params))
+        given.include?(key) && ![nil, '', [], {}].include?(params[key])
+      end
+
+      def self.binary_upload?(params)
         path = params[:ipa] || params[:apk]
-        UI.user_error!("No ipa or apk were given") unless path
+        return false unless path
 
-        return path if Helper.test?
+        BINARY_EXTENSIONS.include?(File.extname(path.to_s).downcase)
+      end
 
-        response = self.upload_build(params[:upload_url], path, client_options, params[:timeout])
-        if parse_response(response)
-          UI.success("Build successfully uploaded to Sauce Labs App Distribution.")
-          UI.success("Response:\n#{JSON.pretty_generate(Actions.lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_RESPONSE])}")
+      def self.metrics_to_client(metrics)
+        Array(metrics).map do |metric|
+          case metric.to_sym
+          when :cpu, :memory, :network, :gps, :battery, :mic, :wifi
+            metric.to_s
+          when :phone_signal
+            'phone-signal'
+          else
+            UI.user_error!("Unknown metric: #{metric}")
+          end
+        end
+      end
+
+      def self.options_to_client(options)
+        Array(options).map do |option|
+          case option.to_sym
+          when :shake, :anonymous
+            option.to_s
+          when :video_only_wifi
+            'video-only-wifi'
+          else
+            UI.user_error!("Unknown option: #{option}")
+          end
+        end
+      end
+
+      # Surface the API's own code and message so a lane can act on them, and
+      # keep the whole envelope in lane_context for retry logic.
+      def self.upload_error_message(response)
+        body = response.body
+        Actions.lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_ERROR] = body
+
+        if body.is_a?(Hash) && body['code']
+          "Sauce Labs App Distribution upload failed with code #{body['code']}: #{body['message'] || '(no message)'}"
         else
-          UI.user_error!("Error when trying to upload ipa to Sauce Labs App Distribution")
+          "Sauce Labs App Distribution upload failed with HTTP #{response.status}: #{body.inspect}"
         end
       end
 
       def self.parse_response(response)
-        if response.body && response.body.key?('status') && response.body['status'] == 'ok'
-          Actions.lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_RESPONSE] = response.body
+        return false unless response.body.is_a?(Hash) && response.body['status'] == 'ok'
 
-          return true
-        else
-          UI.error("Error uploading to Sauce Labs App Distribution: #{response.body}")
+        Actions.lane_context[SharedValues::SAUCELABS_APPDIST_UPLOAD_RESPONSE] = response.body
+        # A retry that succeeds must not leave the earlier failure's envelope
+        # behind for a later reader to mistake for this upload's result.
+        Actions.lane_context.delete(SharedValues::SAUCELABS_APPDIST_UPLOAD_ERROR)
 
-          return false
-        end
+        true
       end
       private_class_method :parse_response
 
@@ -189,18 +309,39 @@ module Fastlane
                                        description: "API URL for Sauce Labs App Distribution",
                                        default_value: "https://app.testfairy.com",
                                        optional: true),
+          FastlaneCore::ConfigItem.new(key: :api_version,
+                                       optional: true,
+                                       type: Symbol,
+                                       env_name: "FL_SAUCELABS_APPDIST_API_VERSION",
+                                       description: "Upload transport. This release supports :legacy (the /api/upload endpoint) only; :v3 arrives in plugin 3.x",
+                                       default_value: :legacy,
+                                       verify_block: proc do |value|
+                                         if value.to_sym == :v3
+                                           UI.user_error!("`api_version: :v3` needs plugin 3.x — this is #{Fastlane::SaucelabsAppdist::VERSION}, which uploads over the legacy /api/upload endpoint")
+                                         end
+                                         UI.user_error!("Unknown api_version `#{value}`. This release supports :legacy only") unless value.to_sym == :legacy
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :team_id,
+                                       optional: true,
+                                       env_name: "FL_SAUCELABS_APPDIST_TEAM_ID",
+                                       skip_type_validation: true,
+                                       description: "Team that owns the app. Pass it when the same bundle id exists on more than one of your teams, otherwise the upload is refused with code 136",
+                                       default_value: '',
+                                       verify_block: proc do |value|
+                                         UI.user_error!("The team_id must be a number") unless value.to_s.empty? || value.to_s.match?(/\A\d+\z/)
+                                       end),
           FastlaneCore::ConfigItem.new(key: :testers_groups,
                                        optional: true,
                                        type: Array,
                                        short_option: '-g',
                                        env_name: "FL_SAUCELABS_APPDIST_TESTERS_GROUPS",
-                                       description: "Array of tester groups to be notified",
+                                       description: "Array of tester groups to be notified. Legacy TestFairy only — Mobile App Distribution notifies every tester on the project",
                                        default_value: []),
           FastlaneCore::ConfigItem.new(key: :metrics,
                                        optional: true,
                                        type: Array,
                                        env_name: "FL_SAUCELABS_APPDIST_METRICS",
-                                       description: "Array of metrics to record (cpu,memory,network,phone_signal,gps,battery,mic,wifi)",
+                                       description: "Array of metrics to record (cpu,memory,network,phone_signal,gps,battery,mic,wifi). Legacy TestFairy SDK only",
                                        default_value: []),
           FastlaneCore::ConfigItem.new(key: :comment,
                                        optional: true,
@@ -210,23 +351,26 @@ module Fastlane
           FastlaneCore::ConfigItem.new(key: :auto_update,
                                        optional: true,
                                        env_name: "FL_SAUCELABS_APPDIST_AUTO_UPDATE",
-                                       description: "Allows an easy upgrade of all users to the current version. To enable set to 'on'",
+                                       description: "Allows an easy upgrade of all users to the current version. To enable set to 'on'. Legacy TestFairy only",
                                        default_value: 'off'),
           FastlaneCore::ConfigItem.new(key: :notify,
                                        optional: true,
                                        env_name: "FL_SAUCELABS_APPDIST_NOTIFY",
-                                       description: "Send email to testers",
-                                       default_value: 'off'),
+                                       description: "Send email to testers. Can be 'on', 'off', '1' or '0'",
+                                       default_value: 'off',
+                                       verify_block: proc do |value|
+                                         UI.user_error!("The notify flag can only be on, off, 1 or 0 — any other value silently notifies nobody") unless %w(on off 1 0).include?(value.to_s)
+                                       end),
           FastlaneCore::ConfigItem.new(key: :options,
                                        optional: true,
                                        type: Array,
                                        env_name: "FL_SAUCELABS_APPDIST_OPTIONS",
-                                       description: "Array of options (shake,video_only_wifi,anonymous)",
+                                       description: "Array of options (shake,video_only_wifi,anonymous). Legacy TestFairy SDK only",
                                        default_value: []),
           FastlaneCore::ConfigItem.new(key: :custom,
                                        optional: true,
                                        env_name: "FL_SAUCELABS_APPDIST_CUSTOM",
-                                       description: "Array of custom options. Contact support for more information",
+                                       description: "Array of custom options. Legacy TestFairy only — contact support for more information",
                                        default_value: ''),
           FastlaneCore::ConfigItem.new(key: :timeout,
                                        env_name: "FL_SAUCELABS_APPDIST_TIMEOUT",
@@ -239,6 +383,12 @@ module Fastlane
                                        description: "Custom tags that can be used to organize your builds",
                                        type: Array,
                                        default_value: []),
+          FastlaneCore::ConfigItem.new(key: :metadata,
+                                       optional: true,
+                                       type: Hash,
+                                       env_name: "FL_SAUCELABS_APPDIST_METADATA",
+                                       description: "Arbitrary key-value pairs to store on the build. Each pair is sent as a metadata_<key> field and comes back under `metadata` in the response",
+                                       default_value: {}),
           FastlaneCore::ConfigItem.new(key: :folder_name,
                                        optional: true,
                                        env_name: "FL_SAUCELABS_APPDIST_FOLDER_NAME",
@@ -252,8 +402,17 @@ module Fastlane
                                        verify_block: proc do |value|
                                          UI.user_error!("The landing page mode can only be open or closed") unless %w(open closed).include?(value)
                                        end),
+          FastlaneCore::ConfigItem.new(key: :sync_to_saucelabs,
+                                       optional: true,
+                                       env_name: "FL_SAUCELABS_APPDIST_SYNC_TO_SAUCELABS",
+                                       description: "Also upload the file to Sauce Labs app storage. It can be 'on' or 'off'",
+                                       default_value: 'off',
+                                       verify_block: proc do |value|
+                                         UI.user_error!("The sync to Sauce Labs can only be on or off") unless %w(on off).include?(value)
+                                       end),
           FastlaneCore::ConfigItem.new(key: :upload_to_saucelabs,
                                        optional: true,
+                                       deprecated: "Renamed to `sync_to_saucelabs`, which is the field Mobile App Distribution reads",
                                        env_name: "FL_SAUCELABS_APPDIST_UPLOAD_TO_SAUCELABS",
                                        description: "Upload file directly to Sauce Labs. It can be 'on' or 'off'",
                                        default_value: 'off',
@@ -263,7 +422,22 @@ module Fastlane
           FastlaneCore::ConfigItem.new(key: :platform,
                                        optional: true,
                                        env_name: "FL_SAUCELABS_APPDIST_PLATFORM",
-                                       description: "Use if upload build is not iOS or Android. Contact support for more information",
+                                       description: "Platform of a generic upload. Ignored for .ipa, .apk and .aab, whose platform comes from the binary",
+                                       default_value: ''),
+          FastlaneCore::ConfigItem.new(key: :landing_page_slug,
+                                       optional: true,
+                                       env_name: "FL_SAUCELABS_APPDIST_LANDING_PAGE_SLUG",
+                                       description: "Custom URL token for the landing page, served at /install/<slug>. 6-63 chars: letters, digits, dot, hyphen or underscore",
+                                       default_value: ''),
+          FastlaneCore::ConfigItem.new(key: :community_token,
+                                       optional: true,
+                                       env_name: "FL_SAUCELABS_APPDIST_COMMUNITY_TOKEN",
+                                       description: "Legacy name for `landing_page_slug`",
+                                       default_value: ''),
+          FastlaneCore::ConfigItem.new(key: :app_description,
+                                       optional: true,
+                                       env_name: "FL_SAUCELABS_APPDIST_APP_DESCRIPTION",
+                                       description: "Description text for the landing page. Legacy TestFairy only — Mobile App Distribution never writes it",
                                        default_value: '')
         ]
       end
@@ -279,7 +453,16 @@ module Fastlane
             api_key: "...",
             apk: "../build/app/outputs/apk/qa/release/app-qa-release.apk",
             comment: "Build #{lane_context[SharedValues::BUILD_NUMBER]}",
-           )'
+           )',
+          '# Same bundle id on several teams: name the team so every upload
+          # appends to the same app instead of forking a new one.
+          saucelabs_appdist(
+            api_key: "...",
+            ipa: "./ipa_file.ipa",
+            team_id: 42,
+            landing_page_slug: "my-app-beta",
+            metadata: { branch: "main", ci_build: "1234" },
+          )'
         ]
       end
 
@@ -289,7 +472,8 @@ module Fastlane
 
       def self.output
         [
-          ['SAUCELABS_APPDIST_UPLOAD_RESPONSE', 'Full response from the upload API']
+          ['SAUCELABS_APPDIST_UPLOAD_RESPONSE', 'Full response from the upload API'],
+          ['SAUCELABS_APPDIST_UPLOAD_ERROR', 'Full error envelope (status, code, message) from a failed upload']
         ]
       end
 

data/lib/fastlane/plugin/saucelabs_appdist/version.rb

@@ -1,5 +1,5 @@
 module Fastlane
   module SaucelabsAppdist
-    VERSION = "0.3.1"
+    VERSION = "2.0.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-saucelabs_appdist
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Sauce Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-23 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -157,7 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Sauce Labs plugin for uploading builds to Mobile App Distribution