# Fastlane Plugin for TestApp.io

Source: https://help.testapp.io/fastlane-plugin/

Fastlane plugin to upload both Android (.apk) and iOS (.ipa) apps to [TestApp.io](https://testapp.io/) and notify your team for testing and feedback. One action, both platforms, release notes from git, optional team notifications.

> 🎉 **v2.0.0 — May 28, 2026:** Critical bug fixes, `--api_token` masked in verbose logs, better error messages, and **Ruby 3.0+ required**. [See what changed](https://help.testapp.io/fastlane-plugin/#whats-new-in-v200) · [Full release notes](https://github.com/testappio/fastlane-plugin-testappio/releases/tag/v2.0.0)

## Getting started

This project is a [*Fastlane*](https://github.com/fastlane/fastlane) plugin. To get started with `fastlane-plugin-testappio`, add it to your project:

```sh
fastlane add_plugin testappio
```

That's it. The plugin will install the underlying [ta-cli](https://help.testapp.io/ta-cli/) binary the first time you upload.

## Compatibility

| Plugin version | Ruby | Status |
| --- | --- | --- |
| **2.x** | `>= 3.0` | Active — feature work + security fixes |
| **1.x** | `>= 2.6` | Maintenance only — security fixes through May 2027 |

If your CI image uses Ruby 2.6 or 2.7, pin to `~> 1.0` in your `Pluginfile`:

```ruby
gem "fastlane-plugin-testappio", "~> 1.0"
```

## Configuration

| Key | Description | Env Var | Default |
| --- | --- | --- | --- |
| `api_token` | API token from [portal.testapp.io/profile/tokens](https://portal.testapp.io/profile/tokens) | `TESTAPPIO_API_TOKEN` | — |
| `app_id` | App ID from [portal.testapp.io/apps](https://portal.testapp.io/apps) | `TESTAPPIO_APP_ID` | — |
| `release` | `ios`, `android`, or `both` | `TESTAPPIO_RELEASE` | current platform |
| `apk_file` | Path to the Android `.apk` | `TESTAPPIO_ANDROID_PATH` | gradle's output |
| `ipa_file` | Path to the iOS `.ipa` | `TESTAPPIO_IOS_PATH` | gym's output |
| `release_notes` | Manual release notes shown to testers | `TESTAPPIO_RELEASE_NOTES` | — |
| `git_release_notes` | Use the latest git commit message as release notes | `TESTAPPIO_GIT_RELEASE_NOTES` | `true` |
| `git_commit_id` | Append the latest commit SHA to release notes | `TESTAPPIO_GIT_COMMIT_ID` | `false` |
| `notify` | Notify team members about the new release | `TESTAPPIO_NOTIFY` | `false` |
| `self_update` | Auto-update `ta-cli` when a new version is available | `TESTAPPIO_SELF_UPDATE` | `true` |

*Check the* [*TA-CLI guide*](https://help.testapp.io/ta-cli/) *for what happens under the hood.*

## Usage

The `upload_to_testappio` action takes these parameters:

```ruby
upload_to_testappio(
  api_token: ENV["TESTAPPIO_API_TOKEN"],
  app_id:    ENV["TESTAPPIO_APP_ID"],
  release_notes: "My release notes here...",
  git_release_notes: true,
  git_commit_id: false,
  notify: true,
  self_update: true
)
```

> 💡 You can replace all the parameters with environment variables: see [configuration](https://help.testapp.io/fastlane-plugin/#configuration).

> ⚠️ `api_token` and `app_id` should be kept secret. Use your CI's secret store or environment variables instead of literals.

> 💪 `release`, `apk_file`, and `ipa_file` can be omitted — the plugin detects the platform context and fills them in automatically.

Check the [example Fastfile](https://github.com/testappio/fastlane-plugin-testappio/blob/main/fastlane/Fastfile) for a runnable end-to-end example. Try it by cloning the repo, running `fastlane install_plugins` and `bundle exec fastlane test`.

##### iOS

```ruby
lane :beta do
  increment_build_number
  match(type: "adhoc")
  gym(export_method: "ad-hoc")

  upload_to_testappio(
    api_token: ENV["TESTAPPIO_API_TOKEN"],
    app_id:    ENV["TESTAPPIO_APP_ID"],
    release_notes: "Bug fixes and improvements",
    git_release_notes: true,
    notify: true,
    self_update: true
  )

  clean_build_artifacts # optional
end
```

And finally 🎉

```sh
fastlane ios beta
```

---

##### Android

Optional:

```sh
fastlane add_plugin increment_version_code
```

```ruby
lane :beta do
  increment_version_code # [Optional] fastlane add_plugin increment_version_code

  gradle(task: "clean assembleRelease") # or clean assembleDebug

  upload_to_testappio(
    api_token: ENV["TESTAPPIO_API_TOKEN"],
    app_id:    ENV["TESTAPPIO_APP_ID"],
    release_notes: "Bug fixes and improvements",
    git_release_notes: true,
    notify: true,
    self_update: true
  )
end
```

And finally 🎉

```sh
fastlane android beta
```

---

## What's new in v2.0.0

Released May 28, 2026. [Full release notes on GitHub](https://github.com/testappio/fastlane-plugin-testappio/releases/tag/v2.0.0).

### ⚠️ Breaking

- **Ruby 3.0+ is now required.** Customers on Ruby 2.6 or 2.7 should pin to `~> 1.0` in their `Pluginfile` until they upgrade Ruby. Existing `Gemfile.lock` entries stay on 1.0.5 and won't auto-upgrade.

### 🐛 Fixed

- `fastlane action upload_to_testappio` (the help/docs introspection command) no longer crashes with `NameError`. A typo in the action's metadata was breaking this path — **actual uploads were unaffected**; only the introspection command was broken.
- `validate_file_path` no longer raises `TypeError` when only one of `apk_file` or `ipa_file` is set — fixes iOS-only and Android-only lanes that didn't pass the other file param.
- Uploads no longer fail when `ta-cli` writes warnings or info to stderr — only real `Error:` lines fail the lane now.
- `--api_token` is now masked as `********` in `fastlane --verbose` logs — previously echoed in plain text.

### ✨ Improved

- When an upload fails, the actual `ta-cli` error message now appears in your CI logs (e.g. *"provisioning profile expired"* or *"Invalid authorization"*) — no more generic *"Error while calling ta-cli"*.
- Modern toolchain: rubocop 1.50+, simplecov 0.22, fastlane 2.217.
- GitHub Actions CI matrix across Ruby 3.0–3.3 × ubuntu/macos.
- Test coverage raised from 36.79% to 100% line / 86% branch.

## Best practices

- **Store secrets in env vars or your CI's secret store.** Never commit `api_token` or `app_id` to source control.
- **Use `git_release_notes: true`** for automatic release notes drawn from your latest commit. Pair with descriptive commit messages.
- **Enable `notify: true`** on builds that should reach testers immediately. Disable for internal-only or silent uploads.
- **Leave `self_update: true`** (the default) unless you have a reason to pin `ta-cli` to a specific version.
- **Pin to a major version** (e.g. `~> 2.0`) in your `Pluginfile` to allow non-breaking fixes while protecting against breaking changes.

## Troubleshooting

- **Bundler error on install:** ensure Ruby `>= 3.0` for plugin v2.x. Check with `ruby -v`. If you need Ruby 2.6 / 2.7 compatibility, pin to `~> 1.0`.
- **Upload fails with a `ta-cli` error:** the error message now includes the underlying `ta-cli` output so you can see exactly what went wrong (auth, network, provisioning, etc.). Run with `fastlane --verbose` for full context.
- **Token visible in CI logs:** should never happen in 2.x; tokens are masked as `********`. If you see it in 1.x, upgrade.
- **`fastlane action upload_to_testappio` crashes:** known bug in v1.0.5 (introspection only — uploads unaffected). Fixed in v2.0.0.

For general Fastlane plugin issues, see the [official Fastlane plugins troubleshooting guide](https://docs.fastlane.tools/plugins/plugins-troubleshooting/).

## Using *Fastlane* plugins

Check the [Fastlane Plugins documentation](https://docs.fastlane.tools/plugins/create-plugin/) for more on how the plugin system works.

## About *Fastlane*

*Fastlane* is the easiest way to automate beta deployments and releases for iOS and Android apps. Learn more at [fastlane.tools](https://fastlane.tools/).

---

#### Related articles

- [Setup iOS Project for Fastlane](https://help.testapp.io/setup-ios-project-for-fastlane/)

> **Tip:** Once your CI/CD pipeline uploads a build, team members using the [TestApp.io mobile app](https://help.testapp.io/mobile-app-getting-started/) receive a push notification and can install the build with a single tap. You can also create [share links](https://help.testapp.io/how-to-share/) to distribute builds to external testers and clients.

---

Need help? [Contact us](https://testapp.io/contact-us/). We're happy to assist!