CI/CD Integration - CircleCI

Overview

The apptego/mobile-protect CircleCI orb protects Android and iOS build artifacts inside your CircleCI workflow. It uploads your Android APK or iOS IPA to AppTego, waits for protection to complete, and returns the protected artifact for signing, testing, storage, or release.

The orb validates Android inputs as .apk files and iOS inputs as .ipa files. For Android App Bundle (.aab) workflows, use the Automation API or the AppTego Portal upload flow.

Use this integration when CircleCI is already the place where your release candidates are built and stored. The orb uses standard CircleCI primitives and requires curl, jq, bc, and standard shell utilities in the execution image.

Quick Start

Store your AppTego automation key in CircleCI as APPTEGO_API_KEY, persist the mobile artifact from your build job, then add the orb to .circleci/config.yml:

version: 2.1

orbs:
  apptego: apptego/mobile-protect@1.0.0

jobs:
  build:
    docker:
      - image: cimg/android:2024.10.1
    steps:
      - checkout
      - run:
          name: Build APK
          command: ./gradlew assembleRelease
      - persist_to_workspace:
          root: .
          paths:
            - app/build/outputs/apk/release/

workflows:
  build-and-protect:
    jobs:
      - build
      - apptego/protect:
          requires:
            - build
          file-path: app/build/outputs/apk/release/app-release.apk
          platform: android
          version: prod

Authentication

Sign in to the AppTego Portal.
Open Automation Keys.
Create a key and copy the full value in key_id:key_secret format.
In CircleCI, open Project Settings -> Environment Variables.
Add APPTEGO_API_KEY with the full key as the value.

For organization-wide reuse, store the same variable in a CircleCI Context and attach that context only to workflows allowed to protect mobile artifacts.

Protect Job

The orb provides a convenience job named apptego/protect. It attaches a workspace from upstream jobs and runs the protect command against the configured mobile artifact. Use output-path when you need a predictable protected filename; use the command form inside your own job when you need precise control over artifact storage, signing, or downstream handoff.

Parameter	Required	Default	Description
`file-path`	Yes	-	Path to the `.apk` or `.ipa` file.
`platform`	Yes	-	`android` or `ios`.
`api-key`	No	`APPTEGO_API_KEY`	Name of the environment variable holding the automation key.
`api-url`	No	`https://api.apptego.com`	AppTego API base URL.
`version`	No	`prod`	Configuration version: `dev`, `staging`, or `prod`.
`output-path`	No	Input file with `-protected` suffix	Output path for the protected binary.
`poll-interval`	No	`15`	Seconds between status checks.
`timeout`	No	`1800`	Maximum seconds to wait for completion.
`workspace-path`	No	`.`	Path where the upstream workspace is attached.
`persist-output`	No	`true`	Persist root-level `.apk` and `.ipa` files for downstream jobs.

The convenience job's persist-output behavior is based on root-level APK/IPA glob patterns. If downstream jobs need the protected output, set output-path to a root-level file such as app-protected.apk, or use the protect command in your own job and explicitly store or persist the configured output-path.

Protect Command

Use the protect command inside your own job when you need full control over workspace attachment, signing, test execution, artifact naming, or release gates:

version: 2.1

orbs:
  apptego: apptego/mobile-protect@1.0.0

jobs:
  build-and-protect:
    docker:
      - image: cimg/android:2024.10.1
    steps:
      - checkout
      - run: ./gradlew assembleRelease
      - apptego/protect:
          file-path: app/build/outputs/apk/release/app-release.apk
          platform: android
          version: staging
          output-path: output/app-staging-protected.apk
          timeout: 3600
      - store_artifacts:
          path: output/app-staging-protected.apk
          destination: protected-apk

workflows:
  main:
    jobs:
      - build-and-protect

Examples

Android APK

workflows:
  protect_android:
    jobs:
      - apptego/protect:
          file-path: app/build/outputs/apk/release/app-release.apk
          platform: android
          version: prod

Android App Bundle

The CircleCI orb does not accept .aab files because its Android input validation requires .apk. Use the Automation API for App Bundle workflows.

iOS IPA

workflows:
  protect_ios:
    jobs:
      - apptego/protect:
          file-path: build/MyApp.ipa
          platform: ios
          version: prod

Outputs

After a successful protect step, the orb exports these variables through $BASH_ENV for later steps in the same job:

Variable	Description
`AF_JOB_ID`	AppTego protection job ID.
`AF_STATUS`	Final status, normally `completed`.
`AF_OUTPUT_FILE`	Path to the downloaded protected file.
`AF_DURATION`	Total protection time in seconds.

Large File Support

Files 100 MB or larger use AppTego multipart upload automatically. No workflow changes are required.

Release Workflow Tips

Tip	Why it helps
Persist the exact mobile artifact path from the build job.	The protection job can only upload files available in its workspace.
Use CircleCI Contexts for production secrets.	Limits who and what can access automation keys.
Keep Android and iOS jobs separate.	Lets each platform use the right image, runner, and timeout.
Store the protected artifact and AppTego job ID.	Makes support and release audit easier.
Run downstream tests against the protected output.	Confirms the artifact you plan to ship.

Troubleshooting

Error	Likely cause	Fix
`401 - Invalid API key`	Key is missing, expired, or malformed	Recreate the automation key and update `APPTEGO_API_KEY`.
`400 - Missing required field`	Required parameter missing, invalid, or using an unsupported extension	Check `file-path`, `platform`, `version`, and the file extension.
`Timed out`	Protection did not finish within `timeout`	Increase `timeout` or inspect the build in AppTego.
`File not found`	The artifact path is wrong or the workspace was not attached	Confirm the upstream build persisted the exact file path.
`jq: command not found` or `bc: command not found`	Execution image does not include a required utility	Use a CircleCI image with `curl`, `jq`, and `bc`, or install them before the protect step.
Orb command not found	Orb import missing or misspelled	Confirm `apptego: apptego/mobile-protect@1.0.0` is declared under `orbs`.
`429` build limit error	Concurrent build limit reached	Wait for in-progress protection jobs to finish or adjust workflow parallelism.