feature: support binary upload and publish flow trigger as independent options

Author: BrkYld

README.md

@@ -1,9 +1,7 @@
 ## Appcircle Publish
 
-Upload an application binary (`.ipa`, `.apk`, or `.aab`) directly to an Appcircle
-**Publish** profile from your GitHub workflow. The uploaded binary becomes a new
-app version on the target Publish profile, ready for the profile's configured
-app store publishing flow.
+Upload an application binary to an Appcircle **Publish** profile and/or trigger
+its publish flow (app store publishing) directly from your GitHub workflow.
 
 Learn more about
 [Appcircle Publish](https://appcircle.io/publish-to-stores?utm_source=github&utm_medium=plugin&utm_campaign=publish).
@@ -31,33 +29,90 @@ To generate a Personal API Token:
 
 ![Token Generation](images/PAT.png)
 
+## What the action does
+
+The action has two independent switches — `upload` and `publish` — both default
+to `false`. **You must enable at least one.** Create the Publish profile in
+Appcircle first; the action targets it by name (profile names are unique per
+platform).
+
+| `upload` | `publish` | Behavior |
+|:--------:|:---------:|----------|
+| `true`  | `false` | Upload `appPath` as a new app version on the profile. |
+| `false` | `true`  | Trigger the publish flow for the profile's **current release candidate**. |
+| `true`  | `true`  | Upload `appPath`, **mark the new version as release candidate**, then trigger the publish flow for it. |
+| `false` | `false` | Error — nothing to do. |
+
+**Rules:**
+
+- **In-progress guard:** if a publish is already running for the target profile,
+  the action does **not** start a new one and fails fast.
+- **Release candidate:** when both `upload` and `publish` are `true`, the freshly
+  uploaded version is automatically marked as the release candidate before it is
+  published. In publish-only mode, the profile's existing release candidate is
+  published.
+- **Progress:** while publishing, the action polls the publish status and prints
+  step-by-step progress until the flow succeeds or fails.
+
+> **Manual-approval steps:** if the profile's publish flow contains a manual step
+> (e.g. "Get Approval via Email"), the flow will wait for that action and the
+> plugin will keep polling until it completes or the poll times out. For CI use,
+> prefer publish flows without manual gates.
+
 ## How to use Appcircle Publish Action
 
-This action uploads a binary to an existing Publish profile. Create the Publish
-profile in Appcircle first, then reference it by name. Publish profile names are
-unique per platform.
+**Upload only:**
 
 ```yml
-- name: Upload App to Appcircle Publish
-  id: upload-to-appcircle-publish
+- name: Upload to Appcircle Publish
   uses: appcircleio/appcircle-publish-githubaction
   with:
     personalAPIToken: ${{ secrets.AC_PERSONAL_API_TOKEN }}
-    platform: PLATFORM # "ios" or "android"
+    platform: ios # or android
     publishProfile: PUBLISH_PROFILE_NAME
-    appPath: APP_PATH
+    upload: 'true'
+    appPath: ./app.ipa
 ```
 
-- `personalAPIToken`: The Appcircle Personal API token is utilized to
-  authenticate and secure access to Appcircle services, ensuring that only
-  authorized users can perform actions within the platform.
-- `platform`: Target platform of the Publish profile. Must be `ios` or
+**Publish only (publishes the profile's current release candidate):**
+
+```yml
+- name: Trigger Appcircle Publish
+  uses: appcircleio/appcircle-publish-githubaction
+  with:
+    personalAPIToken: ${{ secrets.AC_PERSONAL_API_TOKEN }}
+    platform: ios
+    publishProfile: PUBLISH_PROFILE_NAME
+    publish: 'true'
+```
+
+**Upload and publish (uploads, marks it release candidate, then publishes):**
+
+```yml
+- name: Upload and Publish to Appcircle
+  uses: appcircleio/appcircle-publish-githubaction
+  with:
+    personalAPIToken: ${{ secrets.AC_PERSONAL_API_TOKEN }}
+    platform: android
+    publishProfile: PUBLISH_PROFILE_NAME
+    upload: 'true'
+    publish: 'true'
+    appPath: ./app.aab
+```
+
+### Inputs
+
+- `personalAPIToken` (required): Appcircle Personal API Token used to
+  authenticate and secure access to Appcircle services.
+- `platform` (required): Target platform of the Publish profile — `ios` or
   `android`.
-- `publishProfile`: Name of the Publish profile to upload the binary to. The
-  name is resolved to the profile for the selected platform.
-- `appPath`: Indicates the file path to the application that will be uploaded to
-  the Appcircle Publish profile. For iOS use a `.ipa` file; for Android use an
-  `.apk` or `.aab` file.
+- `publishProfile` (required): Name of the Publish profile to target. Resolved to
+  the profile for the selected platform.
+- `upload` (optional, default `false`): Upload `appPath` as a new app version.
+- `publish` (optional, default `false`): Trigger the profile's publish flow.
+- `appPath` (required when `upload` is `true`): Path to the application file. For
+  iOS use a `.ipa` file; for Android use a `.apk` or `.aab` file.
+- `authEndpoint` / `apiEndpoint` (optional): self-hosted endpoints — see below.
 
 ### Self-Hosted Appcircle
 
@@ -68,13 +123,13 @@ they default to the Appcircle cloud (`https://auth.appcircle.io` and
 change.
 
 ```yml
-- name: Upload App to Appcircle Publish
+- name: Trigger Appcircle Publish
   uses: appcircleio/appcircle-publish-githubaction
   with:
     personalAPIToken: ${{ secrets.AC_PERSONAL_API_TOKEN }}
-    platform: PLATFORM # "ios" or "android"
+    platform: ios
     publishProfile: PUBLISH_PROFILE_NAME
-    appPath: APP_PATH
+    publish: 'true'
     authEndpoint: https://auth.your-appcircle-domain.com
     apiEndpoint: https://api.your-appcircle-domain.com
 ```

action.yml

@@ -1,6 +1,8 @@
 name: 'Appcircle Publish'
 author: 'appcircleio'
-description: 'Upload an application binary to an Appcircle Publish profile.'
+description:
+  'Upload a binary to an Appcircle Publish profile and/or trigger its publish
+  flow.'
 
 branding:
   icon: 'upload-cloud'
@@ -28,15 +30,29 @@ inputs:
     required: true
   publishProfile:
     description:
-      'Name of the Publish profile to upload the binary to. Profile names are
-      unique per platform.'
+      'Name of the Publish profile to target. Profile names are unique per
+      platform.'
     required: true
+  upload:
+    description:
+      "Upload the binary at 'appPath' as a new app version on the profile.
+      Defaults to false. At least one of 'upload' or 'publish' must be true."
+    required: false
+    default: 'false'
+  publish:
+    description:
+      "Trigger the profile's publish flow. Defaults to false. When both 'upload'
+      and 'publish' are true, the freshly uploaded version is marked as release
+      candidate and published; when only 'publish' is true, the profile's
+      current release candidate is published. A new publish is never started if
+      one is already in progress for the profile."
+    required: false
+    default: 'false'
   appPath:
     description:
-      'Specify the path to your application file. For iOS, this can be a .ipa
-      file path. For Android, specify the .apk or .aab file
-      path'
-    required: true
+      "Path to the application file. Required when 'upload' is true. For iOS use
+      a .ipa file; for Android use a .apk or .aab file."
+    required: false
 runs:
   using: 'node20'
   main: 'dist/index.js'