GitHub Integration

The Setup Patchwing GitHub Action allows you to integrate Patchwing into your existing GitHub Workflows.

Prerequisites

✅ Patchwing CLI is installed on your machine

✅ You are logged into a Patchwing account.

Quick Start

To integrate Patchwing into your CI, use the setup-patchwing action. The setup-patchwing action downloads Patchwing and adds it to the system path.

name: Patchwing Workflow Example

on:
  workflow_dispatch:

jobs:
  example:
    defaults:
      run:
        shell: bash

    runs-on: ubuntu-latest

    steps:
      # Use the setup-patchwing action to configure Patchwing
      - name: 🦋 Setup Patchwing
        uses: AstralWing/setup-patchwing@v1
        with:
          cache: true # Optionally cache your Patchwing installation

      # Now we're able to use Patchwing CLI in our workflow
      - name: 🚀 Use Patchwing
        run: patchwing --version

In the above workflow, we’re using the setup-patchwing action to configure Patchwing in our CI and in subsequent steps we can execute any Patchwing commands.

Authentication

Most Patchwing functionality, like creating releases and patches, requires authentication. To authenticate in your CI, create an API key from the Patchwing Console:

Go to Account → API Keys.
Click Create API Key.
Give the key a name (e.g., “GitHub Actions — my-app”), choose an expiration, and select a permission level.
Copy the key value — it is only shown once.

Use this key as your PATCHWING_TOKEN in CI. The environment variable name is unchanged from previous versions.

See API Keys for details on permission levels and other key management options.

Next, copy the generated PATCHWING_TOKEN and navigate to your GitHub repository secrets via:

"Settings" -> "Secrets and variables" -> "Actions".

Then, click "New repository secret" and paste your PATCHWING_TOKEN:

name: PATCHWING_TOKEN
secret: <THE GENERATED PATCHWING_TOKEN>

Now we can use the PATCHWING_TOKEN in our GitHub workflow to perform authenticated functions such as creating patches 🎉

Create Releases

The simplest way to create a release is using the official Patchwing GitHub Actions:

name: Patchwing Release

on:
  workflow_dispatch:

env:
  PATCHWING_TOKEN: ${{ secrets.PATCHWING_TOKEN }}

jobs:
  release:
    defaults:
      run:
        shell: bash

    runs-on: ubuntu-latest

    steps:
      - name: 📚 Git Checkout
        uses: actions/checkout@v3

      - name: 🦋 Setup Patchwing
        uses: AstralWing/setup-patchwing@v1
        with:
          cache: true

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: 🚀 Patchwing Release
        uses: AstralWing/patchwing-release@v1
        with:
          platform: android # or 'ios'

The patchwing-release action also outputs the release version:

- name: 🚀 Patchwing Release
  id: patchwing-release
  uses: AstralWing/patchwing-release@v1
  with:
    platform: android # or 'ios'

- name: 📝 Output Release Version
  run: echo ${{ steps.patchwing-release.outputs.release-version }}

Create Patches

name: Patchwing Patch

on:
  workflow_dispatch:

env:
  PATCHWING_TOKEN: ${{ secrets.PATCHWING_TOKEN }}

jobs:
  patch:
    defaults:
      run:
        shell: bash

    runs-on: ubuntu-latest

    steps:
      - name: 📚 Git Checkout
        uses: actions/checkout@v3

      - name: 🦋 Setup Patchwing
        uses: AstralWing/setup-patchwing@v1
        with:
          cache: true

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      # Note: all signing information (key.properties, etc.) must be set up on
      # this runner for `patchwing patch android` to work.
      - name: 🚀 Patchwing Patch
        uses: AstralWing/patchwing-patch@v1
        with:
          platform: android # or 'ios'

:::

tip The patchwing-patch action also outputs the patch number:

- name: 🚀 Patchwing Patch
  id: patchwing-patch
  uses: AstralWing/patchwing-patch@v1
  with:
    platform: android # or 'ios'

- name: 📝 Output Patch Version
  run: echo ${{ steps.patchwing-patch.outputs.patch-number }}

:::

For an example of a fully automated development workflow, see our Development Workflow Guide.

Development Workflow Guide Learn how to set up a fully automated development workflow with Patchwing.