# GitHub Action with Fastlane Plugin

Source: https://help.testapp.io/github-action-with-fastlane-plugin/

[GitHub Action](https://help.testapp.io/github-action/) with TestApp.io [Fastlane plugin](https://help.testapp.io/fastlane-plugin/) allows you to build and upload both Android & iOS apps to TestApp.io to notify your testers for testing and feedback.

> **Plugin v2.x requires Ruby 3.0+.** If your CI image still uses Ruby 2.6 or 2.7, pin to `~> 1.0` in your Pluginfile until you upgrade Ruby. See [Compatibility](https://help.testapp.io/fastlane-plugin/#compatibility) for details.

## Configuration

| Key | Description | Env Var | Default |
| --- | --- | --- | --- |
| `api_token` | You can get it from [portal.testapp.io/profile/tokens](https://portal.testapp.io/profile/tokens) | `TESTAPPIO_API_TOKEN` |  |
| `app_id` | You can get it from your app page at [portal.testapp.io/apps](https://portal.testapp.io/apps) | `TESTAPPIO_APP_ID` |  |
| `release` | It can be either `both`, `android`, or `ios` | `TESTAPPIO_RELEASE` |  |
| `apk` | Path to the Android APK file | `TESTAPPIO_ANDROID_PATH` |  |
| `ipa` | Path to the iOS IPA file | `TESTAPPIO_IOS_PATH` |  |
| `release_notes` | Manually add the release notes to be displayed for the testers | `TESTAPPIO_RELEASE_NOTES` |  |
| `git_release_notes` | Collect release notes from the latest git commit message to be displayed for the testers: `true` or `false` | `TESTAPPIO_GIT_RELEASE_NOTES` | `true` |
| `git_commit_id` | Include the last commit ID in the release notes (works with both release notes options): `true` or `false` | `TESTAPPIO_GIT_COMMIT_ID` | `false` |
| `notify` | Send notifications to your team members about this release: `true` or `false` | `TESTAPPIO_NOTIFY` | `false` |
| `self_update` | Auto-update `ta-cli` when a new version is available | `TESTAPPIO_SELF_UPDATE` | `true` |

*Check* [*TA-CLI*](https://help.testapp.io/ta-cli/) *for more info*

## iOS

We will demonstrate with our sample iOS project, [testappio-ios-sample-app](https://github.com/testappio/ios-sample-app), to show how GitHub Action + [Fastlane](https://help.testapp.io/setup-ios-project-for-fastlane/) + TestApp.io plugin works.

### Configure iOS project for Fastlane

**1. Install Fastlane**

The below command works for most cases. If not, please read this. [Setup Fastlane](https://docs.fastlane.tools/getting-started/ios/setup/)

```bash
gem install fastlane
```

**2. Init Fastlane**

In the iOS project folder:

```bash
bundle exec fastlane init
```

Follow the wizard, it will create `./fastlane/Appfile` with your Apple ID and team.

**3. Init Match**

[Fastlane **match**](https://docs.fastlane.tools/actions/match/) is a tool for generating all necessary certificates, provisioning profiles and storing them in a Git repository encrypted.

Create a private empty GitHub repository for storing certificates and provisioning profiles.

```bash
bundle exec fastlane match init
```

Follow the instructions, provide the new empty git repository when asked, and it will create the `Matchfile`.

> This Git repository will be used to store your certificates and profiles.

**4. Generate the certificate and provisioning profile**

```bash
bundle exec fastlane match adhoc
```

Following the instructions, it will generate certificates/profiles and store them in the Git repository specified in the previous step.

> Provide a matching password for encrypting the certificates and profiles in the Git repository.

**5. Select provisioning profiles in Xcode**

The newly created certificates and profiles should now be possible to select inside your project. Open Xcode and go to **Signing & Capabilities**.

> Don't choose **Automatically Manage Signing**

**6. Add the `testappio` plugin for Fastlane**

```bash
bundle exec fastlane add_plugin testappio
```

**7. Configure GitHub Secrets**

Create the following repository-level secrets in your GitHub repository (Settings → Secrets and variables → Actions):

- `MATCH_PASSWORD`, the password you specified while generating the certificates and profiles
- `FASTLANE_PASSWORD`, the password of your Apple ID
- `MATCH_GIT_BASIC_AUTHORIZATION`, for accessing the certificate/profile repository (see below)
- `TESTAPPIO_API_TOKEN`, from [portal.testapp.io/profile/tokens](https://portal.testapp.io/profile/tokens)
- `TESTAPPIO_APP_ID`, from your app page at [portal.testapp.io/apps](https://portal.testapp.io/apps)

To generate `MATCH_GIT_BASIC_AUTHORIZATION`, navigate to [GitHub Tokens](https://github.com/settings/tokens) to create a **Personal Access Token**, then run:

```bash
echo -n your_github_username:your_personal_access_token | base64
```

### Run the pipeline

**8. Create the lane**

Create `./fastlane/Fastfile` and copy the below content:

```ruby
default_platform(:ios)

platform :ios do

  desc "Build the adhoc and upload to TestApp.io"
  lane :development do
    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: "My release notes here...",
      notify: true,
      self_update: true
    )
  end
  
end
```

More info on the Fastlane plugin: [testappio actions](https://help.testapp.io/fastlane-plugin/#usage)

You may already have your lane in place. copy the `upload_to_testappio` action and put it into your pipeline after the **IPA** export.

**9. Create the GitHub Workflow**

Create `.github/workflows/ios.yml` under your project root folder:

```yaml
name: Build & upload IPA to TestApp.io

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  ios:
    name: Build and upload to TestApp.io
    runs-on: macos-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
      - uses: maierj/fastlane-action@v3.1.0
        env:
          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
          FASTLANE_PASSWORD: ${{ secrets.FASTLANE_PASSWORD }}
          TESTAPPIO_API_TOKEN: ${{ secrets.TESTAPPIO_API_TOKEN }}
          TESTAPPIO_APP_ID: ${{ secrets.TESTAPPIO_APP_ID }}
          MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_BASIC_AUTHORIZATION }}
        with:
          lane: 'ios development'
          verbose: true
```

**10. Commit and push** the change to trigger the GitHub Action.

## Android

We will demonstrate with our sample Android project [testappio-android-sample](https://github.com/testappio/android-sample-app), how GitHub Action + Fastlane + TestApp.io plugin works.

**1. Create repository-level Secrets** `TESTAPPIO_API_TOKEN` and `TESTAPPIO_APP_ID`

**2. Create `.github/workflows/android.yml` file**

```yaml
name: Build & upload APK to TestApp.io

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  android:
    name: Build and upload to TestApp.io
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
      - uses: maierj/fastlane-action@v3.1.0
        env:
          TESTAPPIO_API_TOKEN: ${{ secrets.TESTAPPIO_API_TOKEN }}
          TESTAPPIO_APP_ID: ${{ secrets.TESTAPPIO_APP_ID }}
        with:
          lane: 'android development'
          verbose: true
```

**3. Create `fastlane/Fastfile`**

```ruby
default_platform(:android)

platform :android do

  desc "Submit a new Build to TestApp.io"
  lane :development do

    increment_version_code

    gradle(task: "clean assembleDebug")
  
    upload_to_testappio(
      api_token: ENV["TESTAPPIO_API_TOKEN"],
      app_id:    ENV["TESTAPPIO_APP_ID"],
      release_notes: "My release notes here...",
      notify: true,
      self_update: true
    )
  end
end
```

**4. Commit and push** the change to trigger the GitHub Action.

---

#### Related Articles

- [GitHub Actions Setup](https://help.testapp.io/github-action/)
- [Fastlane Plugin](https://help.testapp.io/fastlane-plugin/)
- [ta-cli Documentation](https://help.testapp.io/ta-cli/)
- [ta-cli on GitHub](https://github.com/testappio/cli)

> **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!