Automation and Scripting with AppForShare
By Nimrah Bilal · · 6 min read

You can automate AppForShare by uploading builds from your CI pipeline with the AppForShare command line tool, the GitHub Action or the fastlane plugin and an API token, and by sending build events to Slack, Microsoft Teams, Google Chat, Discord or your own server with webhooks. Every build your pipeline produces then gets an install link, release notes and a store readiness result without anyone opening a browser. CI uploads and webhooks are part of the Pro and Team plans.
This guide shows what can be automated, how to set it up in common CI systems, and what is not automated today.
What you can automate
| Task | How | Plan |
|---|---|---|
| Upload a build and get its install link | CLI, GitHub Action, fastlane plugin or Gradle plugin with an API token | Pro, Team |
| Attach release notes | --notes or --notes-file | Pro, Team |
| Keep one stable link for the newest build | --channel beta puts the build into a channel | Pro, Team |
| Stop the pipeline on a store blocker | --fail-on blocked exits with code 2, the build stays uploaded | Pro, Team |
| Post new builds to chat | Slack, Microsoft Teams, Google Chat, Discord or Telegram | Pro, Team |
| Trigger your own scripts | Generic webhook signed with HMAC-SHA256 | Pro, Team |
| Share a build with testers when it is ready | --groups or --testers on upload | Team |
Uploading from CI with the CLI
The CLI needs Node 18 or newer and an API token, which you create under Dashboard, Settings. Store the token as a secret in your CI system, never in the repository. The basic command is:
export APPFORSHARE_TOKEN=afs_your_token
npx appforshare upload build/MyApp.ipa --notes "Fixes the login crash"
The command prints the install link and the store readiness result (ready, review, blocked or unknown) when the build is ready. Useful options:
--notesor--notes-file: release notes for testers.--channel beta: puts the build into a channel, whose one link always opens the newest build in it.--fail-on blocked: exits with code 2 when the store readiness check finds a blocker. The build is still uploaded and its link works.--json: prints the URL, slug, name, version, expiry and readiness as JSON for later steps.--no-wait: returns as soon as the upload is queued.
Large builds go up in 32 MB chunks and resume after a dropped connection.
GitHub Actions
Add the token as a repository secret named APPFORSHARE_TOKEN, then add the AppForShare Action after your build step:
- name: Share build
id: afs
uses: appforshare/appforshare-action@v1
with:
file: app/build/outputs/apk/release/app-release.apk
token: ${{ secrets.APPFORSHARE_TOKEN }}
release-notes: ${{ github.event.head_commit.message }}
channel: beta
- run: echo "Install link: ${{ steps.afs.outputs.url }}"
fastlane
Add the plugin once with fastlane add_plugin appforshare. The appforshare action picks up the file that gym or your Gradle task just built:
lane :beta do
gym(export_method: "ad-hoc")
appforshare(release_notes: "Fixes the login crash", channel: "beta")
end
The token comes from the APPFORSHARE_TOKEN environment variable.
Bitrise, GitLab CI and other systems
Any job that can run Node can run the same command. On Bitrise, add APPFORSHARE_TOKEN as a Secret and a Script step after the build step that runs npx --yes appforshare upload "$BITRISE_IPA_PATH" (or $BITRISE_APK_PATH and $BITRISE_AAB_PATH for Android). An AppForShare step for the Bitrise step library is in review; until it is listed, the Script step does the same. The Bitrise guide has the full step, and the CI documentation covers GitLab CI, CircleCI, Bitbucket, Jenkins, Azure Pipelines, Xcode Cloud, Codemagic and Expo EAS. Building on Expo EAS? Use AppForShare with Expo EAS shows Connect Expo, which shares every finished EAS internal build through an EAS build webhook with no CI step (Pro and Team), and an Expo Workflows job that uploads the build. Building on Codemagic? Use AppForShare with Codemagic shows a publishing script that uploads only when the build passed (Codemagic runs publishing scripts even after a failed build), and Connect Codemagic, which imports finished builds with a Codemagic API token and nothing in codemagic.yaml (Pro and Team).
Webhooks for notifications and scripts
Webhooks send an HTTP request when something happens in your account. AppForShare can format them for Slack, Microsoft Teams, Google Chat and Discord, or send a generic JSON payload to your own endpoint. Telegram, with your own bot from @BotFather and a chat id, gets short messages for build ready, build installed and tester feedback. Events include:
build.ready: a build finished processing and its install link works.build.failed: an upload could not be turned into a build.build.installed: someone started an install, with device, OS version, model and country.feedback.new: a tester sent feedback from the install page.store.statusandstore.review: an App Store or Google Play release changed state, or a new store review came in (needs a store connection).bandwidth.warning: monthly bandwidth reached 80% or 100%.
Generic webhooks are signed with HMAC-SHA256 so your server can check that a request really came from AppForShare. Retries send the same event id, so you can skip duplicates. See the webhooks documentation for the payload format and a signature check example.
Common uses: post every new build to a QA channel, open a ticket in your own tracker when a build fails, or alert the team when bandwidth is running low.
What is not automated
- AppForShare does not build your app on its own machines. Your CI produces the APK or IPA; AppForShare shares it. On Pro and Team it can set up builds on your own GitHub Actions minutes with one pull request.
- Uploaded .apk files are never re-signed. With an App Store Connect connection (Pro and Team), an Admin can register device UDIDs on Apple, remake the ad hoc profile and re-sign the uploaded .ipa with it instead of building again. On Team, Hands free does the re-sign automatically when the project has no GitHub build.
- Releases never go out on their own. Sending a version for App Store review or changing a Google Play rollout is done by an Admin of your workspace from the dashboard.
- CI uploads and webhooks are not available on the Free plan or for guest uploads.
A typical automated flow
- A developer pushes to the main branch.
- CI builds a signed APK or Ad Hoc IPA.
- The CLI or the Action uploads it with the commit message as release notes and puts it into the Beta channel.
- The store readiness check runs; a blocker can stop the pipeline.
- The
build.readywebhook posts the install link to Slack, Teams or Google Chat. - On Team, the tester groups named on upload get an email that a new build is ready.
- Testers install from the link or QR code on their phones.
Frequently asked questions
Can I upload builds to AppForShare from CI?
Yes, on Pro and Team. Create an API token under Dashboard, Settings and use the CLI with npx, the GitHub Action, the fastlane plugin or the Gradle plugin in any CI, including Bitrise, GitLab CI and Jenkins.
Which chat tools can get notifications?
Slack, Microsoft Teams, Google Chat, Discord and Telegram, plus generic signed webhooks, on Pro and Team. Events include build ready, build failed, build installed, tester feedback, store status and bandwidth warnings.
Does AppForShare build or sign my app?
Your own build system creates and signs the APK or IPA, or AppForShare sets up a build on your own GitHub Actions (Pro and Team). AppForShare never re-signs uploaded .apk files; the only Android signing it does is for .aab uploads, which become one APK for testers. On Pro and Team it can re-sign an uploaded .ipa with a new ad hoc, development or enterprise profile, saved as a new build.
Is there an integration with Jira or GitHub issues?
Tester feedback reports can be sent to Linear or Jira Cloud as an issue, one way (Pro and Team). There is no GitHub issues integration; you can connect other tools by receiving AppForShare webhooks on your server.


