fastlane-plugin-sync_devices 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a36daeccb8615f994ee412d9f469e416698636b975796152a2b2c8f27d889b43
+  data.tar.gz: 29a12e29ba18a01f7958eb98ac1b2c4e97a22a4c1f256f3521cf4f67bed4f529
+SHA512:
+  metadata.gz: e3987bece7d43b523a1df6cf1303b39511f310ae2701c0903f385d2e714a7ff61f734f8c21daa3d884de50c118557f0793db7e71337dc748bdaa245684ae335a
+  data.tar.gz: a6ed24116431af31c5cd6fe141c9fc365de7be8ebcb88e3631eb1d461e24958c6c98aec0730d500aae4dbc85d53173db414634ffb7b58a8ae834d708ea8b2134

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## master
+
+## 0.1.0
+
+* Initial release - [@manicmaniac](https://github.com/manicmaniac)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Ryosuke Ito <rito.0305@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# sync\_devices plugin
+
+[![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-sync_devices)
+[![Test](https://github.com/manicmaniac/fastlane-plugin-sync_devices/actions/workflows/test.yml/badge.svg)](https://github.com/manicmaniac/fastlane-plugin-sync_devices/actions/workflows/test.yml)
+
+## Getting Started
+
+This project is a [fastlane](https://github.com/fastlane/fastlane) plugin. To get started with `fastlane-plugin-sync_devices`, add it to your project by running:
+
+```bash
+fastlane add_plugin sync_devices
+```
+
+## About sync\_devices
+
+This plugin provides a single action `sync_devices`.
+
+`sync_devices` synchronizes your devices with Apple Developer Portal.
+
+This plugin works similarly to fastlane official [register\_devices](https://docs.fastlane.tools/actions/register_devices/) plugin, but `sync_devices` can disable, enable and rename devices on Apple Developer Portal while `register_devices` is only capable to create new devices.
+
+Since we can only actually _delete_ a device once a year, `sync_devices` does not _delete_ devices but just disables them when they were removed from a devices file. It's safe because you can re-enable devices whenever you want.
+
+## Basic Usage
+
+First of all, you need to create your own `devices.tsv` under your project repository. It is a simple tab-separated text file like the following example.
+
+```
+Device ID	Device Name	Device Platform
+01234567-89ABCDEF01234567	NAME1	ios
+abcdef0123456789abcdef0123456789abcdef01	NAME2	ios
+01234567-89AB-CDEF-0123-4567890ABCDE	NAME3	mac
+ABCDEF01-2345-6789-ABCD-EF0123456789	NAME4	mac
+```
+
+Then you can run `sync_devices` from command line.
+
+Run `sync_devices` in dry-run mode, which does not change remote devices, so that you can see what will be done when it actually runs.
+
+```
+fastlane run sync_devices devices_file:devices.tsv dry_run:true
+```
+
+After carefully checking if the result is the same as expected, run
+
+```
+fastlane run sync_devices devices_file:devices.tsv
+```
+
+You will see the remote devices are synchronized with your devices.tsv.
+
+
+## Advanced Usage
+
+### Use Property List file instead of TSV
+
+Apple Developer Portal also accepts a devices file in Property List format like this.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Device UDIDs</key>
+	<array>
+		<dict>
+			<key>deviceIdentifier</key>
+			<string>01234567-89ABCDEF01234567</string>
+			<key>deviceName</key>
+			<string>NAME1</string>
+			<key>devicePlatform</key>
+			<string>ios</string>
+		</dict>
+	</array>
+</dict>
+</plist>
+```
+
+If you want to use Property List format, just pass the file to `sync_devices`.
+
+```
+fastlane run sync_devices devices_file:devices.deviceids
+```
+
+Following Apple's guide, I added `.deviceids` file extension but you can use standard `.xml` or `.plist` as well.
+
+```
+fastlane run sync_devices devices_file:devices.xml
+```
+
+## Example
+
+Check out the [example `Fastfile`](fastlane/Fastfile) to see how to use this plugin. Try it by cloning the repo, running `fastlane install_plugins` and `bundle exec fastlane test`.
+
+## Run tests for this plugin
+
+To run both the tests, and code style validation, run
+
+```
+bundle exec rake
+```
+
+To automatically fix many of the styling issues, use
+```
+bundle exec rake rubocop:autocorrect
+```
+
+You can check other useful tasks by running
+
+```
+bundle exec rake -T
+```
+
+## Issues and Feedback
+
+For any other issues and feedback about this plugin, please submit it to [this repository](https://github.com/manicmaniac/fastlane-plugin-sync_devices).
+
+## Troubleshooting
+
+If you have trouble using plugins, check out the [Plugins Troubleshooting](https://docs.fastlane.tools/plugins/plugins-troubleshooting/) guide.
+
+## Using _fastlane_ Plugins
+
+For more information about how the `fastlane` plugin system works, check out the [Plugins documentation](https://docs.fastlane.tools/plugins/create-plugin/).
+
+## About _fastlane_
+
+_fastlane_ is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out [fastlane.tools](https://fastlane.tools).

data/lib/fastlane/plugin/sync_devices/actions/sync_devices_action.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'credentials_manager'
+require 'fastlane/action'
+require_relative '../helper/sync_devices_helper'
+
+module Fastlane # rubocop:disable Style/Documentation
+  # @see https://rubydoc.info/gems/fastlane/FastlaneCore/UI
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  # @see https://rubydoc.info/gems/fastlane/Fastlane/Actions
+  module Actions
+    # Fastlane action to synchronize remote devices on Apple Developer Portal with local devices file.
+    class SyncDevicesAction < Action # rubocop:disable Metrics/ClassLength
+      include Fastlane::Helper::SyncDevicesHelper
+
+      # The main entry point of this plugin.
+      #
+      # @param params [Hash] options passed to this plugin. See {.available_options} for details.
+      # @option params [Boolean] :dry_run
+      # @option params [String] :devices_file
+      # @option params [String, nil] :api_key_path
+      # @option params [Hash, nil] :api_key
+      # @option params [String, nil] :team_id
+      # @option params [String, nil] :team_name
+      # @option params [String, nil] :username
+      # @return [void]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.run Fastlane::Action.run
+      def self.run(params)
+        require 'spaceship/connect_api'
+
+        devices_file = params[:devices_file]
+        UI.user_error!('You must pass `devices_file`. Please check the readme.') unless devices_file
+        spaceship_login(params)
+        new_devices = DevicesFile.load(devices_file)
+
+        UI.message('Fetching list of currently registered devices...')
+        current_devices = Spaceship::ConnectAPI::Device.all
+        patch = DevicesPatch.new(current_devices, new_devices)
+        patch.apply!(dry_run: params[:dry_run])
+
+        UI.success('Successfully registered new devices.')
+      end
+
+      # Authenticates the user with AppStore Connect API or Apple Developer Portal.
+      #
+      # @param (see .run)
+      # @return [void]
+      def self.spaceship_login(params)
+        api_token = Spaceship::ConnectAPI::Token.from(hash: params[:api_key], filepath: params[:api_key_path])
+        if api_token
+          UI.message('Creating authorization token for App Store Connect API')
+          Spaceship::ConnectAPI.token = api_token
+        elsif Spaceship::ConnectAPI.token
+          UI.message('Using existing authorization token for App Store Connect API')
+        else
+          UI.message("Login to App Store Connect (#{params[:username]})")
+          credentials = CredentialsManager::AccountManager.new(user: params[:username])
+          Spaceship::ConnectAPI.login(credentials.user, credentials.password, use_portal: true, use_tunes: false)
+          UI.message('Login Successful')
+        end
+      end
+      private_class_method :spaceship_login
+
+      # Description of this plugin.
+      #
+      # @return [String]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.description Fastlane::Action.description
+      def self.description
+        'Synchronize your devices with Apple Developer Portal.'
+      end
+
+      # Authors of this plugin.
+      #
+      # @return [Array<String>]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.authors Fastlane::Action.authors
+      def self.authors
+        ['Ryosuke Ito']
+      end
+
+      # Detailed description of this plugin.
+      #
+      # @return [String]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.details Fastlane::Action.details
+      def self.details
+        <<~DETAILS
+          This will synchronize iOS/Mac devices with the Apple Developer Portal so that you can include them in your provisioning profiles.
+          Unlike `register_devices` action, this action may disable, enable or rename devices.
+          Maybe it sounds dangerous but actually it does not delete anything, so you can recover the changes by yourself if needed.
+
+          The action will connect to the Apple Developer Portal using AppStore Connect API.
+        DETAILS
+      end
+
+      # Available options of this plugin.
+      #
+      # @return [Array<FastlaneCore::ConfigItem>]
+      #
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.available_options Fastlane::Action.available_options
+      # @see https://rubydoc.info/gems/fastlane/FastlaneCore/ConfigItem FastlaneCore::ConfigItem
+      def self.available_options # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        [
+          FastlaneCore::ConfigItem.new(
+            key: :dry_run,
+            env_name: 'FL_SYNC_DEVICES_DRY_RUN',
+            description: 'Do not modify the registered devices but just print what will be done',
+            type: Boolean,
+            default_value: false,
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :devices_file,
+            env_name: 'FL_SYNC_DEVICES_FILE',
+            description: 'Provide a path to a file with the devices to register. ' \
+                         'For the format of the file see the examples',
+            optional: true,
+            verify_block: proc do |value|
+              UI.user_error!("Could not find file '#{value}'") unless File.exist?(value)
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :api_key_path,
+            env_names: %w[FL_SYNC_DEVICES_API_KEY_PATH APP_STORE_CONNECT_API_KEY_PATH],
+            description: 'Path to your App Store Connect API Key JSON file ' \
+                         '(https://docs.fastlane.tools/app-store-connect-api/#using-fastlane-api-key-json-file)',
+            optional: true,
+            conflicting_options: [:api_key],
+            verify_block: proc do |value|
+              UI.user_error!("Couldn't find API key JSON file at path '#{value}'") unless File.exist?(value)
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :api_key,
+            env_names: %w[FL_SYNC_DEVICES_API_KEY APP_STORE_CONNECT_API_KEY],
+            description: 'Your App Store Connect API Key information ' \
+                         '(https://docs.fastlane.tools/app-store-connect-api/#using-fastlane-api-key-hash-option)',
+            type: Hash,
+            default_value: Fastlane::Actions.lane_context[Fastlane::Actions::SharedValues::APP_STORE_CONNECT_API_KEY],
+            default_value_dynamic: true,
+            optional: true,
+            sensitive: true,
+            conflicting_options: [:api_key_path]
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :team_id,
+            env_name: 'SYNC_DEVICES_TEAM_ID',
+            code_gen_sensitive: true,
+            default_value: CredentialsManager::AppfileConfig.try_fetch_value(:team_id),
+            default_value_dynamic: true,
+            description: "The ID of your Developer Portal team if you're in multiple teams",
+            optional: true,
+            verify_block: proc do |value|
+              ENV['FASTLANE_TEAM_ID'] = value.to_s
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :team_name,
+            env_name: 'SYNC_DEVICES_TEAM_NAME',
+            description: "The name of your Developer Portal team if you're in multiple teams",
+            optional: true,
+            code_gen_sensitive: true,
+            default_value: CredentialsManager::AppfileConfig.try_fetch_value(:team_name),
+            default_value_dynamic: true,
+            verify_block: proc do |value|
+              ENV['FASTLANE_TEAM_NAME'] = value.to_s
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :username,
+            env_name: 'DELIVER_USER',
+            description: 'Optional: Your Apple ID',
+            optional: true,
+            default_value: CredentialsManager::AppfileConfig.try_fetch_value(:apple_id),
+            default_value_dynamic: true
+          )
+        ]
+      end
+
+      # Whether if this plugin is supported on the platform.
+      #
+      # @param _platform [Symbol] unused
+      # @return [true]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.is_supported%3F Fastlane::Action.is_supported?
+      def self.is_supported?(_platform) # rubocop:disable Naming/PredicateName
+        true
+      end
+
+      # Example usages of this plugin.
+      #
+      # @return [Array<String>]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.example_code Fastlane::Action.example_code
+      def self.example_code
+        [
+          <<~EX_1,
+            # Provide TSV file
+            sync_devices(devices_file: '/path/to/devices.txt')
+          EX_1
+          <<~EX_2,
+            # Provide Property List file, with configuring credentials
+            sync_devices(
+              devices_file: '/path/to/devices.deviceids',
+              team_id: 'ABCDEFGHIJ',
+              api_key_path: '/path/to/api_key.json'
+            )
+          EX_2
+          <<~EX_3
+            # Just check what will occur
+            sync_devices(devices_file: '/path/to/devices.txt', dry_run: true)
+          EX_3
+        ]
+      end
+
+      # Category of this plugin.
+      #
+      # @return [Symbol]
+      # @see https://rubydoc.info/gems/fastlane/Fastlane%2FAction.category Fastlane::Action.category
+      def self.category
+        :code_signing
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/command.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'spaceship/connect_api'
+
+module Fastlane
+  module Helper
+    module SyncDevicesHelper
+      # Namespace to organize command classes.
+      module Command
+        # Abstract base class of command object.
+        #
+        # @attr device [Spaceship::ConnectAPI::Device]
+        Base = Struct.new(:device) do
+          # Communicate with AppStore Connect and change the remote device.
+          # @abstract
+          # @return [void]
+          def run
+            # :nocov:
+            raise NotImplementedError
+            # :nocov:
+          end
+
+          # Description of this command.
+          # @abstract
+          # @return [String]
+          def description
+            # :nocov:
+            raise NotImplementedError
+            # :nocov:
+          end
+        end
+
+        # Command to do nothing.
+        class Noop < Base
+          # @return (see Base#run)
+          def run
+            # Does nothing.
+          end
+
+          # @return (see Base#description)
+          def description
+            "Skipped #{device.name} (#{device.udid})"
+          end
+        end
+
+        # Command to disable an existing device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/modify_a_registered_device
+        class Disable < Base
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.disable(device.udid)
+          end
+
+          # @return (see Base#description)
+          def description
+            "Disabled #{device.name} (#{device.udid})"
+          end
+        end
+
+        # Command to enable an existing device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/modify_a_registered_device
+        class Enable < Base
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.enable(device.udid)
+          end
+
+          # @return (see Base#description)
+          def description
+            "Enabled #{device.name} (#{device.udid})"
+          end
+        end
+
+        # Command to rename an existing device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/modify_a_registered_device
+        class Rename < Base
+          # @return [String]
+          attr_reader :name
+
+          # @param device [Spaceship::ConnectAPI::Device]
+          # @param name [String]
+          def initialize(device, name)
+            super(device)
+            @name = name
+          end
+
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.rename(device.udid, name)
+          end
+
+          # @return (see Base#description)
+          def description
+            "Renamed #{device.name} to #{name} (#{device.udid})"
+          end
+        end
+
+        # Command to disable and rename an existing device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/modify_a_registered_device
+        class DisableAndRename < Base
+          # @return [String]
+          attr_reader :name
+
+          # @param device [Spaceship::ConnectAPI::Device]
+          # @param name [String]
+          def initialize(device, name)
+            super(device)
+            @name = name
+          end
+
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.modify(
+              device.udid,
+              enabled: false,
+              new_name: name
+            )
+          end
+
+          # @return (see Base#description)
+          def description
+            "Disabled and renamed #{device.name} to #{name} (#{device.udid})"
+          end
+        end
+
+        # Command to enable and rename an existing device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/modify_a_registered_device
+        class EnableAndRename < Base
+          # @return [String] name
+          attr_reader :name
+
+          # @param device [Spaceship::ConnectAPI::Device]
+          # @param name [String]
+          def initialize(device, name)
+            super(device)
+            @name = name
+          end
+
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.modify(
+              device.udid,
+              enabled: true,
+              new_name: name
+            )
+          end
+
+          # @return (see Base#description)
+          def description
+            "Enabled and renamed #{device.name} to #{name} (#{device.udid})"
+          end
+        end
+
+        # Command to register a new device.
+        # @see https://developer.apple.com/documentation/appstoreconnectapi/register_a_new_device
+        class Create < Base
+          # @return (see Base#run)
+          def run
+            Spaceship::ConnectAPI::Device.create(
+              name: device.name,
+              platform: device.platform,
+              udid: device.udid
+            )
+          end
+
+          # @return (see Base#description)
+          def description
+            "Created #{device.name} (#{device.udid})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/device_patch.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'command'
+
+module Fastlane
+  module Helper
+    module SyncDevicesHelper
+      # Represents differences between 2 devices.
+      class DevicePatch
+        # @return [Spaceship::ConnectAPI::Device]
+        attr_reader :old_device, :new_device
+
+        # @param old_device [Spaceship::ConnectAPI::Device, nil]
+        # @param new_device [Spaceship::ConnectAPI::Device, nil]
+        def initialize(old_device, new_device)
+          @old_device = old_device
+          @new_device = new_device
+        end
+
+        # @return [Boolean]
+        def renamed?
+          !!old_device && !!new_device && old_device.name != new_device.name
+        end
+
+        # @return [Boolean]
+        def enabled?
+          !!old_device && !old_device.enabled? && !!new_device&.enabled?
+        end
+
+        # @return [Boolean]
+        def disabled?
+          !!old_device && old_device.enabled? && !new_device&.enabled?
+        end
+
+        # @return [Boolean]
+        def created?
+          old_device.nil? && !!new_device&.enabled?
+        end
+
+        # @return [Boolean]
+        def platform_changed?
+          !!old_device && !!new_device && old_device.platform != new_device.platform
+        end
+
+        # @return [Command::Base]
+        # @raise [UnsupportedOperation]
+        def command # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+          raise UnsupportedOperation.change_platform(old_device, new_device) if platform_changed?
+
+          case [renamed?, enabled?, disabled?, created?]
+          when [false, false, false, false]
+            Command::Noop.new(old_device)
+          when [false, false, false, true]
+            Command::Create.new(new_device)
+          when [false, false, true, false]
+            Command::Disable.new(old_device)
+          when [false, true, false, false]
+            Command::Enable.new(old_device)
+          when [true, false, false, false]
+            Command::Rename.new(old_device, new_device.name)
+          when [true, false, true, false]
+            Command::DisableAndRename.new(old_device, new_device.name)
+          when [true, true, false, false]
+            Command::EnableAndRename.new(old_device, new_device.name)
+          else
+            # :nocov:
+            raise UnsupportedOperation.internal_inconsistency(self, old_device, new_device)
+            # :nocov:
+          end
+        end
+      end
+
+      # Generic error that is raised if no operation is defined in AppStore Connect API for diff of devices.
+      class UnsupportedOperation < StandardError
+        # @return [Spaceship::ConnectAPI::Device]
+        attr_reader :old_device, :new_device
+
+        # @param message [String]
+        # @param old_device [Spaceship::ConnectAPI::Device]
+        # @param new_device [Spaceship::ConnectAPI::Device]
+        def initialize(message, old_device, new_device)
+          super(message)
+          @old_device = old_device
+          @new_device = new_device
+        end
+
+        # @param old_device [Spaceship::ConnectAPI::Device]
+        # @param new_device [Spaceship::ConnectAPI::Device]
+        # @return [UnsupportedOperation]
+        def self.change_platform(old_device, new_device)
+          message = "Cannot change platform of the device '#{new_device.udid}' " \
+                    "(#{old_device.platform} -> #{new_device.platform})"
+          new(message, old_device, new_device)
+        end
+
+        # @param patch [DevicePatch]
+        # @param old_device [Spaceship::ConnectAPI::Device]
+        # @param new_device [Spaceship::ConnectAPI::Device]
+        # @return [UnsupportedOperation]
+        def self.internal_inconsistency(patch, old_device, new_device)
+          info = {
+            renamed?: patch.renamed?,
+            enabled?: patch.enabled?,
+            disabled?: patch.disabled?,
+            created?: patch.created?
+          }
+          new(
+            "Cannot change #{old_device} to #{new_device} because of internal inconsistency. #{info}",
+            old_device,
+            new_device
+          )
+        end
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/devices_file.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Fastlane
+  module Helper
+    module SyncDevicesHelper
+      # Collection of methods that manipulates TSV or XML devices file.
+      #
+      # @see https://developer.apple.com/account/resources/downloads/Multiple-Upload-Samples.zip
+      module DevicesFile # rubocop:disable Metrics/ModuleLength
+        # Loads a devices file and parse it as an array of devices.
+        # If the file extension is one of +.deviceids+, +.plist+ and +.xml+, this method delegates to {.load_plist},
+        # otherwise to {.load_tsv}.
+        #
+        # @param path [String] path to the output file
+        # @return [Array<Spaceship::ConnectAPI::Device>]
+        def self.load(path)
+          return load_plist(path) if %w[.deviceids .plist .xml].include?(File.extname(path))
+
+          load_tsv(path)
+        end
+
+        # @param path [String]
+        # @return [Array<Spaceship::ConnectAPI::Device>]
+        def self.load_tsv(path)
+          require 'csv'
+          require 'spaceship/connect_api'
+
+          table = CSV.read(path, headers: true, col_sep: "\t")
+          validate_headers(table.headers, path)
+
+          devices = table.map.with_index(2) do |row, line_number|
+            validate_row(row, path, line_number)
+            Spaceship::ConnectAPI::Device.new(
+              nil,
+              {
+                name: row['Device Name'],
+                udid: row['Device ID'],
+                platform: parse_platform(row['Device Platform'], path),
+                status: Spaceship::ConnectAPI::Device::Status::ENABLED
+              }
+            )
+          end
+          validate_devices(devices, path)
+          devices
+        end
+
+        # @param path [String]
+        # @return [Array<Spaceship::ConnectAPI::Device>]
+        def self.load_plist(path)
+          require 'cfpropertylist'
+          require 'spaceship/connect_api'
+
+          plist = CFPropertyList::List.new(file: path)
+          items = CFPropertyList.native_types(plist.value)['Device UDIDs']
+          devices = items.map.with_index do |item, index|
+            validate_dict_item(item, index, path)
+            Spaceship::ConnectAPI::Device.new(
+              nil,
+              {
+                name: item['deviceName'],
+                udid: item['deviceIdentifier'],
+                platform: parse_platform(item['devicePlatform'], path),
+                status: Spaceship::ConnectAPI::Device::Status::ENABLED
+              }
+            )
+          end
+          validate_devices(devices, path)
+          devices
+        end
+
+        # Dumps devices to devices file specified by path.
+        # This method delegates to either of {.dump_tsv} or {.dump_plist} depending on +format+.
+        #
+        # @param devices [Array<Spaceship::ConnectAPI::Device>] device objects to dump
+        # @param path [String] path to the output file
+        # @param format [:tsv, :plist] output format
+        # @return [void]
+        def self.dump(devices, path, format: :tsv)
+          case format
+          when :tsv
+            dump_tsv(devices, path)
+          when :plist
+            dump_plist(devices, path)
+          else
+            raise "Unsupported format '#{format}'."
+          end
+        end
+
+        # @param devices [Array<Spaceship::ConnectAPI::Device>] device objects to dump
+        # @param path [String] path to the output file
+        # @return [void]
+        def self.dump_tsv(devices, path)
+          require 'csv'
+
+          CSV.open(path, 'w', col_sep: "\t", headers: true, write_headers: true) do |csv|
+            csv << HEADERS
+            devices.each do |device|
+              csv << [device.udid, device.name, device.platform]
+            end
+          end
+        end
+
+        # @param devices [Array<Spaceship::ConnectAPI::Device>] device objects to dump
+        # @param path [String] path to the output file
+        # @return [void]
+        def self.dump_plist(devices, path)
+          require 'cfpropertylist'
+
+          plist = CFPropertyList::List.new
+          plist.value = CFPropertyList.guess(
+            {
+              'Device UDIDs' => devices.map do |device|
+                {
+                  deviceIdentifier: device.udid,
+                  deviceName: device.name,
+                  devicePlatform: device.platform.downcase
+                }
+              end
+            }
+          )
+          plist.save(path, CFPropertyList::List::FORMAT_XML)
+        end
+
+        # Maximum length of a device name that is permitted by Apple Developer Portal.
+        #
+        # @return [Integer]
+        MAX_DEVICE_NAME_LENGTH = 50
+
+        # @param devices [Array<Spaceship::ConnectAPI::Device>] device objects to dump
+        # @param path [String]
+        # @return [void]
+        # @raise [InvalidDevicesFile]
+        def self.validate_devices(devices, path) # rubocop:disable Metrics/AbcSize
+          seen_udids = []
+          devices.each do |device|
+            udid = device.udid&.downcase
+            unless udid.match(udid_regex_for_platform(device.platform))
+              raise InvalidDevicesFile.invalid_udid(device.udid, path)
+            end
+            raise InvalidDevicesFile.udid_not_unique(device.udid, path) if seen_udids.include?(udid)
+
+            if device.name.size > MAX_DEVICE_NAME_LENGTH
+              raise InvalidDevicesFile.device_name_too_long(device.name, path)
+            end
+
+            seen_udids << udid
+          end
+        end
+        private_class_method :validate_devices
+
+        # @param platform_string [String]
+        # @param path [String]
+        # @return [String]
+        def self.parse_platform(platform_string, path)
+          Spaceship::ConnectAPI::BundleIdPlatform.map(platform_string || 'ios')
+        rescue RuntimeError => e
+          if e.message.include?('Cannot find a matching platform')
+            raise InvalidDevicesFile.unknown_platform(platform_string, path)
+          end
+
+          raise
+        end
+        private_class_method :parse_platform
+
+        HEADERS = ['Device ID', 'Device Name', 'Device Platform'].freeze
+        private_constant :HEADERS
+
+        SHORT_HEADERS = HEADERS[0..1].freeze
+        private_constant :SHORT_HEADERS
+
+        # @param [Array<String>] headers
+        # @param [String] path
+        # @raise [InvalidDevicesFile]
+        def self.validate_headers(headers, path)
+          raise InvalidDevicesFile.invalid_headers(path, 1) unless [HEADERS, SHORT_HEADERS].include?(headers.compact)
+        end
+        private_class_method :validate_headers
+
+        # @param row [CSV::Row]
+        # @param path [String]
+        # @param line_number [Integer]
+        # @return [void]
+        # @raise [InvalidDevicesFile]
+        def self.validate_row(row, path, line_number)
+          case row.fields.compact.size
+          when 0, 1
+            raise InvalidDevicesFile.columns_too_short(path, line_number)
+          when 2, 3
+            # Does nothing
+          else
+            raise InvalidDevicesFile.columns_too_long(path, line_number)
+          end
+        end
+        private_class_method :validate_row
+
+        REQUIRED_KEYS = %w[deviceName deviceIdentifier].freeze
+        private_constant :REQUIRED_KEYS
+
+        # @param item [Hash<String, String>]
+        # @param index [Integer]
+        # @param path [String]
+        # @return [void]
+        # @raise [InvalidDevicesFile]
+        def self.validate_dict_item(item, index, path)
+          REQUIRED_KEYS.each do |key|
+            unless item.key?(key)
+              entry = ":Device UDIDs:#{index}:#{key}"
+              raise InvalidDevicesFile.missing_key(entry, path)
+            end
+          end
+        end
+        private_class_method :validate_dict_item
+
+        # @param platform [String]
+        # @return [Regexp]
+        # @raise [TypeError] when platform is not in {Spaceship::ConnectAPI::BundleIdPlatform::ALL}.
+        def self.udid_regex_for_platform(platform)
+          case platform
+          when Spaceship::ConnectAPI::BundleIdPlatform::IOS
+            # @see https://www.theiphonewiki.com/wiki/UDID
+            /^(?:[0-9]{8}-[0-9a-f]{16}|[0-9a-f]{40})$/
+          when Spaceship::ConnectAPI::BundleIdPlatform::MAC_OS
+            /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+          else
+            # :nocov:
+            raise TypeError, "Unknown platform '#{platform}' is not in #{Spaceship::ConnectAPI::BundleIdPlatform::ALL}."
+            # :nocov:
+          end
+        end
+        private_class_method :udid_regex_for_platform
+      end
+
+      # Generic error that is raised if device file is not in the valid format.
+      class InvalidDevicesFile < StandardError
+        # URL of example devices files.
+        SAMPLE_FILE_URL = 'https://developer.apple.com/account/resources/downloads/Multiple-Upload-Samples.zip'
+
+        # @return [String]
+        attr_reader :path
+        # @return [Integer]
+        attr_reader :line_number
+        # @return [String, nil]
+        attr_reader :entry
+
+        # @param message [String]
+        # @param path [String]
+        # @param line_number [String, nil]
+        # @param entry [String, nil]
+        def initialize(message, path, line_number: nil, entry: nil)
+          super(format(message, { location: [path, line_number].join(':'), url: SAMPLE_FILE_URL }))
+          @path = path
+          @line_number = line_number
+          @entry = entry
+        end
+
+        # @param path [String]
+        # @param line_number [Integer]
+        # @return [InvalidDevicesFile]
+        def self.invalid_headers(path, line_number)
+          message = 'Invalid header line at %<location>s, please provide a file according to ' \
+                    'the Apple Sample UDID file (%<url>s)'
+          new(message, path, line_number: line_number)
+        end
+
+        # @param path [String]
+        # @param line_number [Integer]
+        # @return [InvalidDevicesFile]
+        def self.columns_too_short(path, line_number)
+          message = 'Invalid device line at %<location>s, ensure you are using tabs (NOT spaces). ' \
+                    "See Apple's sample/spec here: %<url>s"
+          new(message, path, line_number: line_number)
+        end
+
+        # @param path [String]
+        # @param line_number [Integer]
+        # @return [InvalidDevicesFile]
+        def self.columns_too_long(path, line_number)
+          message = 'Invalid device line at %<location>s, please provide a file according to ' \
+                    'the Apple Sample UDID file (%<url>s)'
+          new(message, path, line_number: line_number)
+        end
+
+        # @param entry [String]
+        # @param path [String]
+        # @return [InvalidDevicesFile]
+        def self.missing_key(entry, path)
+          message = "Invalid device file at %<location>s, each item must have a required key '#{entry}', " \
+                    "See Apple's sample/spec here: %<url>s"
+          new(message, path, entry: entry)
+        end
+
+        # @param udid [String]
+        # @param path [String]
+        # @return [InvalidDevicesFile]
+        def self.invalid_udid(udid, path)
+          new("Invalid UDID '#{udid}' at %<location>s, the UDID is not in the correct format", path)
+        end
+
+        # @param udid [String]
+        # @param path [String]
+        # @return [InvalidDevicesFile]
+        def self.udid_not_unique(udid, path)
+          message = "Invalid UDID '#{udid}' at %<location>s, there's another device with the same UDID is defined"
+          new(message, path)
+        end
+
+        # @param name [String]
+        # @param path [String]
+        # @return [InvalidDevicesFile]
+        def self.device_name_too_long(name, path)
+          message = "Invalid device name '#{name}' at %<location>s, a device name " \
+                    "must be less than or equal to #{DevicesFile::MAX_DEVICE_NAME_LENGTH} characters long"
+          new(message, path)
+        end
+
+        # @param platform [String]
+        # @param path [String]
+        # @return [InvalidDevicesFile]
+        def self.unknown_platform(platform, path)
+          new("Unknown platform '#{platform}' at %<location>s", path)
+        end
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/devices_patch.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'device_patch'
+
+module Fastlane # rubocop:disable Style/Documentation
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module Helper
+    module SyncDevicesHelper
+      # Represents a collection of {DevicePatch}.
+      class DevicesPatch
+        # @return [Spaceship::ConnectAPI::Device]
+        attr_reader :old_devices, :new_devices
+        # @return [Array<DevicePatch>]
+        attr_reader :commands
+
+        # @param old_devices [Array<Spaceship::ConnectAPI::Device>]
+        # @param new_devices [Array<Spaceship::ConnectAPI::Device>]
+        def initialize(old_devices, new_devices) # rubocop:disable Metrics/AbcSize
+          @old_devices = old_devices
+          @new_devices = new_devices
+
+          old_device_by_udid = old_devices.group_by { |d| d.udid.downcase }.transform_values(&:first)
+          new_device_by_udid = new_devices.group_by { |d| d.udid.downcase }.transform_values(&:first)
+          @commands = (old_device_by_udid.keys + new_device_by_udid.keys)
+                      .sort
+                      .uniq
+                      .map do |udid|
+            old_device = old_device_by_udid[udid]
+            new_device = new_device_by_udid[udid]
+            DevicePatch.new(old_device, new_device).command
+          end
+        end
+
+        # @param dry_run [Boolean]
+        # @return [void]
+        def apply!(dry_run: false)
+          @commands.each do |command|
+            if dry_run
+              UI.message("(dry-run) #{command.description}")
+            else
+              command.run
+              UI.message(command.description)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/sync_devices/helper/sync_devices_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Fastlane
+  # @see https://rubydoc.info/gems/fastlane/Fastlane/Helper Fastlane::Helper
+  module Helper
+    # Root namespace of +fastlane-plugin-sync_devices+ helpers.
+    module SyncDevicesHelper
+    end
+  end
+end
+
+require_relative 'sync_devices_helper/devices_file'
+require_relative 'sync_devices_helper/devices_patch'

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Fastlane
+  module SyncDevices
+    # Gem version of fastlane-plugin-sync_devices.
+    VERSION = '0.1.0'
+  end
+end

data/lib/fastlane/plugin/sync_devices.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'sync_devices/version'
+require_relative 'sync_devices/actions/sync_devices_action'
+
+module Fastlane
+  # Root namespace of +fastlane-plugin-sync_devices+ plugin.
+  module SyncDevices
+    # @return [Array<String>]
+    def self.all_classes
+      Dir[File.expand_path('**/{actions,helper}/*.rb', __dir__)]
+    end
+  end
+end
+
+Fastlane::SyncDevices.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-sync_devices
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryosuke Ito
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-04-18 00:00:00.000000000 Z
+dependencies: []
+description: Synchronize your devices with Apple Developer Portal.
+email: rito.0305@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fastlane/plugin/sync_devices.rb
+- lib/fastlane/plugin/sync_devices/actions/sync_devices_action.rb
+- lib/fastlane/plugin/sync_devices/helper/sync_devices_helper.rb
+- lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/command.rb
+- lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/device_patch.rb
+- lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/devices_file.rb
+- lib/fastlane/plugin/sync_devices/helper/sync_devices_helper/devices_patch.rb
+- lib/fastlane/plugin/sync_devices/version.rb
+homepage: https://github.com/manicmaniac/fastlane-plugin-sync_devices
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/manicmaniac/fastlane-plugin-sync_devices/issues
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/manicmaniac/fastlane-plugin-sync_devices
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Synchronize your devices with Apple Developer Portal.
+test_files: []