Skip to main content

Android - DevApp Setup

This guide covers cloning the DevApp repository, configuring authentication, and running the app for the first time.

Before you start

Confirm you have completed the Pre-Development Checklist. In particular, you need a Personal Access Token (PAT) generated and copied — see Accounts and Access if you have not done this yet.

1. Clone the repository​

Clone the Android DevApp from Q2's GitLab. SSH is the recommended approach — it uses a key on your machine instead of a password, integrates cleanly with Android Studio, and avoids re-entering credentials on every push.

Option A — SSH (recommended)​

Requirements:

If you do not yet have an SSH key, follow GitLab's guide: Use SSH keys to communicate with GitLab.

Clone:

git clone git@code.q2developer.com:Q2Antilles/native/android/devapp-android.git

Option B — HTTPS (fallback)​

Use HTTPS if SSH is not an option — for example, if you are not set up for SSH key authentication, your network blocks port 22, or your organization restricts SSH altogether.

git clone https://code.q2developer.com/Q2Antilles/native/android/devapp-android.git

When Git prompts for credentials, use your GitLab username and your Personal Access Token as the password. (See Accounts and Access if you have not generated one yet.)

Open the project​

  1. Open Android Studio.
  2. Choose File → Open and select the cloned devapp-android folder.
  3. Allow Android Studio to index the project. The first sync will fail — that is expected, and the next step fixes it.

2. Add your Personal Access Token​

The first Gradle sync fails because it cannot authenticate against Q2's private Maven repository. To fix this, paste your PAT directly into settings.gradle so both your local builds and the Q2 CI pipeline can read it.

Open settings.gradle at the project root and find this block:

maven {
    url "https://code.q2developer.com/api/v4/groups/782/-/packages/maven"
    credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = msdk_repo_token
    }
    authentication {
        header(HttpHeaderAuthentication)
    }
}

Replace the bare msdk_repo_token reference with your token wrapped in quotes:

maven {
    url "https://code.q2developer.com/api/v4/groups/782/-/packages/maven"
    credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = "your_generated_token_here"
    }
    authentication {
        header(HttpHeaderAuthentication)
    }
}

Save the file. You can commit and push this change — when the token is generated with the recommended scopes (api, read_api, read_registry, read_repository), it only has access to repositories you already have access to, so checking it into your own DevApp repository is safe.

If your token is ever exposed outside your organization

Tokens scoped this way are still personal credentials. If you accidentally share one publicly (for example, in a screenshot or public repository), revoke it from Edit profile → Access Tokens in GitLab and generate a new one.

3. Sync Gradle​

After saving settings.gradle, resync the project:

  • Click Sync Now in the yellow notification bar at the top of the editor, or
  • Choose File → Sync Project with Gradle Files.

The first sync downloads Gradle, the Android Gradle Plugin, and every Q2 library — expect it to take several minutes on a fast connection. If the sync completes without errors, the project is ready to run.

If sync fails, see Troubleshooting below.

4. Run the app​

  1. Connect a physical Android device, or start an emulator from Tools → Device Manager.
  2. Click Run (the green ▶ button), or press Shift + F10 (Control + R on macOS).

The DevApp installs on the device and launches automatically.

Troubleshooting​

"Could not resolve msdk_repo_token" / "Could not get unknown property 'msdk_repo_token'"​

Gradle cannot find your token in settings.gradle. Check, in order:

  • The value line is wrapped in quotes: value = "abc...", not value = abc... and not value = msdk_repo_token (the unset placeholder).
  • The token has no extra whitespace, line breaks, or trailing characters inside the quotes.
  • Restart the Gradle daemon after the change: File → Invalidate Caches → Restart.

"401 Unauthorized" from code.q2developer.com​

Your token is invalid or expired. Return to your GitLab profile, generate a new token, and confirm the scopes are api, read_api, read_registry, and read_repository.

SSL handshake or certificate errors​

Your network performs SSL inspection. See Network and Firewall — Custom CA certificates.

"Unsupported Java version"​

The project requires JDK 21. See Java Versions for how to switch versions.

Android Studio asks to install missing SDK components​

On first open, Android Studio may prompt to install the Android SDK platform and build tools that match the project's compileSdk and targetSdk. Accept the prompt. Behind a corporate firewall, this download requires dl.google.com to be reachable — see Network and Firewall.

Gradle sync hangs at "Resolving dependencies" with no error​

Almost always a network problem rather than a build problem:

  • A required host is blocked. Re-run the validation curl commands on the Network and Firewall page.
  • A proxy is in front of you and is not configured. See Proxy configuration.
  • Slow corporate connection — first-time syncs can legitimately take 10+ minutes while Gradle downloads its full dependency graph.

Verifying the project builds before clicking Run​

If you want a clean signal that everything compiles before launching the app, run a command-line build from the project root:

./gradlew assembleDebug

A successful run produces an APK under devapp/build/outputs/apk/debug/.

Anything else​

Contact your Q2 representative or check the repository documentation.

What's next​

DevApp running? Confirm you are on the right JDK with Java Versions, then configure which modules the app loads at Setting Up settings.json.