fastlane-plugin-paper_tools_builds 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 908c8abf1c1c43649aec2095b46ef05c1536dd1ce4702494eb2654510ef4142e
+  data.tar.gz: 556964951b566ef27f528f0be710ddd67b893b5e6d35ce61e356915c9f3c8b8d
+SHA512:
+  metadata.gz: bd9e42c757e48cb02ab14fb76bb7f2bed0a6ebde6e0b2852ee8fc977b5d1c0611ae20c611091b3deff8ecf8716c33ac7c8410b69a34bf70e25c76f4da639a7ec
+  data.tar.gz: 50e08177846dcb5a096138fc86e38f473d779bcd0b26116628a0c39046010663cd608c1fd3a5d33428f421c07bebc78976ae8335711ed9df597f812fefa9faa0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) paper.tools
+
+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,81 @@
+# fastlane-plugin-paper_tools_builds
+
+Upload a build to Builds by paper.tools from a fastlane lane. The
+`paper_tools_builds_upload` action wraps the `builds` CLI, so it inherits the
+resumable multipart upload, the exit codes, and the staging-or-production default
+without reimplementing any of them.
+
+This directory is the source of truth. It is published to RubyGems as
+`fastlane-plugin-paper_tools_builds`. The name portion is underscored because
+fastlane rejects a dash after the `fastlane-plugin-` prefix.
+
+## Setup
+
+Install the CLI, then add the plugin:
+
+```shell
+brew install paper-tools/tap/builds
+fastlane add_plugin paper_tools_builds
+```
+
+`paper_tools_builds_upload` shells out to the `builds` binary, so it must be on
+`PATH` (or pass `binary:` with a path).
+
+## Usage
+
+```ruby
+lane :distribute do
+  build_app(scheme: "App")
+
+  build_id = paper_tools_builds_upload(
+    file: lane_context[SharedValues::IPA_OUTPUT_PATH],
+    channel: "qa",
+    to: "qa,cto@acme.com",
+    version: get_version_number,
+    build_number: get_build_number
+  )
+
+  UI.message("Uploaded build #{build_id}")
+end
+```
+
+Set `BUILDS_TOKEN`, `BUILDS_ORG`, and `BUILDS_APP` in the environment — the token
+never belongs in a Fastfile. The action reads them, and the build id it returns
+is also on `lane_context[SharedValues::PAPER_TOOLS_BUILDS_BUILD_ID]`.
+
+## Options
+
+| Option          | Env            | Description                                    |
+| --------------- | -------------- | ---------------------------------------------- |
+| `file`          | `BUILDS_FILE`  | Path to the `.ipa`, `.apk`, or `.aab`. Required. |
+| `channel`       | `BUILDS_CHANNEL` | The channel to land on. Required.            |
+| `token`         | `BUILDS_TOKEN` | A `builds:write` token. Kept out of argv.      |
+| `to`            |                | Comma-separated recipients.                    |
+| `org`           | `BUILDS_ORG`   | The organisation id.                           |
+| `app`           | `BUILDS_APP`   | The app id.                                    |
+| `api_url`       | `BUILDS_API_URL` | Override the binary's built-in host.         |
+| `version`       |                | The marketing version.                         |
+| `build_number`  |                | The build number.                              |
+| `release_notes` |                | Release notes.                                 |
+| `tags`          |                | Comma-separated tags.                          |
+| `format`        |                | Force the format when the extension is unclear. |
+| `notify`        |                | Notify recipients.                             |
+| `concurrency`   |                | Parallel part uploads.                         |
+| `binary`        |                | Path to the `builds` binary. Defaults to `builds`. |
+
+## A non-zero exit fails the lane
+
+The action fails the lane on any non-zero exit, and the exit code says which
+class it was — auth, validation, quota, network. See the CLI's exit-code table in
+the service `README.md`.
+
+## Development
+
+```shell
+bundle install
+bundle exec rspec
+```
+
+The canonical repository is a private GitLab project, mirrored to GitHub for
+public issues and the RubyGems source link. Push to GitLab; the mirror follows.
+A `v*` tag publishes the gem to RubyGems from CI.

data/lib/fastlane/plugin/paper_tools_builds/actions/paper_tools_builds_upload_action.rb

@@ -0,0 +1,163 @@
+require 'fastlane/action'
+require 'open3'
+require 'json'
+
+module Fastlane
+  module Actions
+    module SharedValues
+      PAPER_TOOLS_BUILDS_BUILD_ID = :PAPER_TOOLS_BUILDS_BUILD_ID
+    end
+
+    # Uploads a build by shelling out to the `builds` binary.
+    #
+    # The binary is the single upload path, so the lane inherits its resumable
+    # multipart upload, its exit codes, and its staging-or-production default
+    # without reimplementing any of it. The token travels in the environment,
+    # never in the argument list, so it stays out of a process listing and a log.
+    class PaperToolsBuildsUploadAction < Action
+      def self.run(params)
+        command = [params[:binary], 'upload', params[:file], '--channel', params[:channel], '--json']
+        command += ['--to', params[:to]] unless params[:to].nil?
+        command += ['--version', params[:version]] unless params[:version].nil?
+        command += ['--build-number', params[:build_number].to_s] unless params[:build_number].nil?
+        command += ['--release-notes', params[:release_notes]] unless params[:release_notes].nil?
+        command += ['--tags', params[:tags]] unless params[:tags].nil?
+        command += ['--format', params[:format]] unless params[:format].nil?
+        command += ['--concurrency', params[:concurrency].to_s] unless params[:concurrency].nil?
+        command += ['--org', params[:org]] unless params[:org].nil?
+        command += ['--app', params[:app]] unless params[:app].nil?
+        command += ['--api-url', params[:api_url]] unless params[:api_url].nil?
+        command += (params[:notify] ? ['--notify'] : ['--no-notify']) unless params[:notify].nil?
+
+        # The token goes in the environment, not the command, so it never lands
+        # in argv. `builds` reads BUILDS_TOKEN there.
+        env = {}
+        env['BUILDS_TOKEN'] = params[:token] unless params[:token].nil?
+
+        UI.message("Uploading #{params[:file]} to channel #{params[:channel]}…")
+        stdout, stderr, status = Open3.capture3(env, *command)
+
+        unless status.success?
+          UI.error(stderr.strip) unless stderr.strip.empty?
+          # The binary's exit code names the failure class — auth, quota,
+          # network — and the lane fails with it rather than swallowing it.
+          UI.user_error!("builds upload failed (exit #{status.exitstatus}).")
+        end
+
+        build = parse(stdout)
+        build_id = build['build_id']
+        Actions.lane_context[SharedValues::PAPER_TOOLS_BUILDS_BUILD_ID] = build_id
+        UI.success("Uploaded. Build #{build_id} is #{build['status']}.")
+        build_id
+      end
+
+      # The `--json` upload response, or an empty hash if it was not JSON. A
+      # non-JSON stdout is not fatal — the upload succeeded — so the id is simply
+      # unavailable rather than an error.
+      def self.parse(stdout)
+        JSON.parse(stdout)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def self.description
+        'Upload a build to Builds by paper.tools'
+      end
+
+      def self.details
+        'Wraps the `builds` CLI. Install it first (brew install ' \
+          'paper-tools/tap/builds), then set a builds:write token in ' \
+          'BUILDS_TOKEN or pass it as `token`.'
+      end
+
+      def self.return_value
+        'The id of the accepted build, also stored in ' \
+          'lane_context[SharedValues::PAPER_TOOLS_BUILDS_BUILD_ID].'
+      end
+
+      def self.authors
+        ['paper.tools']
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :file,
+                                       env_name: 'BUILDS_FILE',
+                                       description: 'Path to the .ipa, .apk, or .aab',
+                                       verify_block: proc do |value|
+                                         UI.user_error!("No file at #{value}") unless File.exist?(value)
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :channel,
+                                       env_name: 'BUILDS_CHANNEL',
+                                       description: 'The channel to land on'),
+          FastlaneCore::ConfigItem.new(key: :token,
+                                       env_name: 'BUILDS_TOKEN',
+                                       description: 'A builds:write API token',
+                                       sensitive: true,
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :to,
+                                       description: 'Comma-separated recipients to distribute to',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :org,
+                                       env_name: 'BUILDS_ORG',
+                                       description: 'The organisation id',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :app,
+                                       env_name: 'BUILDS_APP',
+                                       description: 'The app id',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :api_url,
+                                       env_name: 'BUILDS_API_URL',
+                                       description: 'Override the binary\'s built-in API host',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :version,
+                                       description: 'The marketing version',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :build_number,
+                                       description: 'The build number',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :release_notes,
+                                       description: 'Release notes for this build',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :tags,
+                                       description: 'Comma-separated tags',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :format,
+                                       description: 'Force the format when the extension does not name it',
+                                       optional: true),
+          FastlaneCore::ConfigItem.new(key: :notify,
+                                       description: 'Notify recipients; defaults to the channel setting',
+                                       optional: true,
+                                       is_string: false),
+          FastlaneCore::ConfigItem.new(key: :concurrency,
+                                       description: 'How many parts to upload at once',
+                                       optional: true,
+                                       type: Integer),
+          FastlaneCore::ConfigItem.new(key: :binary,
+                                       description: 'Path to the builds binary',
+                                       optional: true,
+                                       default_value: 'builds'),
+        ]
+      end
+
+      def self.is_supported?(platform)
+        [:ios, :mac, :android].include?(platform)
+      end
+
+      def self.category
+        :building
+      end
+
+      def self.example_code
+        [
+          'paper_tools_builds_upload(
+            file: lane_context[SharedValues::IPA_OUTPUT_PATH],
+            channel: "qa",
+            version: get_version_number,
+            build_number: get_build_number
+          )',
+        ]
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/paper_tools_builds/helper/paper_tools_builds_helper.rb

@@ -0,0 +1,16 @@
+require 'fastlane_core/ui/ui'
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?('UI')
+
+  module Helper
+    class PaperToolsBuildsHelper
+      # Whether the `builds` binary is on PATH, or at the given path. The action
+      # lets the binary report its own absence; this is for a lane that wants to
+      # check first.
+      def self.available?(binary = 'builds')
+        system(binary, '--version', out: File::NULL, err: File::NULL)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+module Fastlane
+  module PaperToolsBuilds
+    VERSION = '0.1.0'
+  end
+end

data/lib/fastlane/plugin/paper_tools_builds.rb

@@ -0,0 +1,15 @@
+require 'fastlane/plugin/paper_tools_builds/version'
+
+module Fastlane
+  # Loads every action and helper the plugin ships, the way `fastlane` expects a
+  # plugin's entry point to.
+  module PaperToolsBuilds
+    def self.all_classes
+      Dir[File.expand_path('**/{actions,helper}/*.rb', File.dirname(__FILE__))]
+    end
+  end
+end
+
+Fastlane::PaperToolsBuilds.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-paper_tools_builds
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- paper.tools
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fastlane
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description:
+email: builds@paper.tools
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/fastlane/plugin/paper_tools_builds.rb
+- lib/fastlane/plugin/paper_tools_builds/actions/paper_tools_builds_upload_action.rb
+- lib/fastlane/plugin/paper_tools_builds/helper/paper_tools_builds_helper.rb
+- lib/fastlane/plugin/paper_tools_builds/version.rb
+homepage: https://builds.paper.tools
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://builds.paper.tools
+  source_code_uri: https://github.com/paper-tools/fastlane-plugin-paper_tools_builds
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Upload builds to Builds by paper.tools from fastlane
+test_files: []