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. settings.gradle reads your token from a Gradle property named msdk_repo_token:

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

Supply that property from your global Gradle properties file, which lives in your home directory outside any project. Because it is never part of the repository, your token cannot be committed by accident, and your local builds still authenticate.

  1. Open (or create) your Gradle home properties file:

    • macOS / Linux: ~/.gradle/gradle.properties
    • Windows: C:\Users\<you>\.gradle\gradle.properties

  2. Add your token on its own line:

    msdk_repo_token=your_generated_token_here

  3. Save the file.

Gradle merges this global file into every build, so the value = msdk_repo_token reference in settings.gradle resolves to your token automatically for local builds.

By default the credential is sent using the Private-Token header, which is what a Personal Access Token needs — so a PAT works with just the line above, no extra configuration. The header name itself is not a secret; it comes from an optional msdk_repo_token_header property that defaults to Private-Token.

Using a deploy token instead

Prefer a GitLab deploy token over a personal one? If you have the Maintainer or Owner role on your repository you can create one yourself (Settings → Repository → Deploy tokens, read_package_registry scope); otherwise request one from your Q2 representative — the Developer role cannot create deploy tokens. Then add one more line to ~/.gradle/gradle.properties so Gradle sends it through the matching header:

msdk_repo_token_header=Deploy-Token

Q2's CI pipeline sets this same variable, so it authenticates with its own deploy token while your local build defaults to a PAT.

danger
Do not edit the msdk_repo_token reference in settings.gradle

Leave the value = msdk_repo_token line exactly as it is — do not rename the property, wrap it in quotes, or hard-code your token there. The Q2 CI pipeline looks for that exact property name and supplies its own token at build time; changing or removing it will break CI builds. Your token belongs only in ~/.gradle/gradle.properties, never in settings.gradle.

If your token is ever exposed outside your organization

Tokens are 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 ~/.gradle/gradle.properties, 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 the msdk_repo_token property. Check, in order:

  • The property is set in your Gradle home file ~/.gradle/gradle.properties (C:\Users\<you>\.gradle\gradle.properties on Windows) as msdk_repo_token=your_token — see Add your Personal Access Token.
  • The token has no extra whitespace, line breaks, quotes, or trailing characters.
  • You did not edit the value = msdk_repo_token line in settings.gradle — it must stay exactly as shipped.
  • 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? The next step is to turn the template into your own project — rename the module, rename the package, set your group id, and remove the example code — in Configure Your Project. After that, confirm you are on the right JDK with Java Versions and configure which modules the app loads at Setting Up settings.json.