# Clone The Repo And Open The KMP Project For The First Time

> Open a real production Kotlin Multiplatform project instead of a toy starter project.

- URL: https://dantech.academy/en/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-02-clone-repo-open-project
- Course: [Mobile Action Pro](https://dantech.academy/en/courses/kotlin-accelerator.md)
- Module: Setup App Running
- Duration: 12 min
- Difficulty: beginner
- Access: Free, full lesson
- Tiếng Việt: https://dantech.academy/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-02-clone-repo-open-project.md

## Objectives

- Authenticate GitHub access with GitHub CLI and clone the private course repository
- Open the correct repository root in Android Studio instead of a nested module folder
- Understand what the first Gradle sync does to a KMP project and classify the first error when sync fails

---

## Lesson Goal

By the end of this lesson you have:

- A GitHub account with access to the private course repository,
- The course codebase cloned into a permanent workspace,
- Android Studio open at the correct project root,
- A clear picture of what the first Gradle sync does to a Kotlin Multiplatform project.

## Before You Clone

Make sure of three things:

- GitHub access: you have an account and can see the private repository.
- Git authentication: your machine can clone code from GitHub.
- Project root: Android Studio opens the repo's root folder.

Official docs:

- [Create a GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github)
- [GitHub CLI](https://cli.github.com/)

## Part 1: Confirm GitHub Access In The Browser

Open the course invite link in your browser first and check that:

1. You are signed in to the same GitHub account you used when you bought the course.
2. The repository page opens and does not return `404`.
3. You can see the green `Code` button or a clone URL.

## Part 2: Choose How To Authenticate

| Method | When to use it                                                     | Example                           |
| ------ | ------------------------------------------------------------------ | --------------------------------- |
| HTTPS  | The simple default; works with a GitHub CLI or credential manager login | `https://github.com/org/repo.git` |
| SSH    | A good fit if you already know SSH keys and how to debug key problems | `git@github.com:org/repo.git`     |

Install [GitHub CLI](https://cli.github.com/) so you don't have to paste a personal access token into the terminal. Then run:

```bash
gh --version
gh auth login
gh auth status
```

Follow the browser login flow. Once `gh auth status` says you are logged in to the right account, your machine has a clean way to authenticate.

Don't paste a personal access token into notes, screenshots, Discord, support messages or shell history.

## Part 3: Create A Permanent Workspace

Put the repo somewhere you will keep for the whole course, not in a random download folder:

```bash
mkdir -p ~/Desktop/kotlin/dan-tech-academy
cd ~/Desktop/kotlin/dan-tech-academy
git clone <course-repo-url>
```

Use the exact private repository URL you were given access to. If the clone says `Repository not found`, check your browser access again. If the clone keeps asking you to authenticate, finish `gh auth login` or the credential manager setup and try again.

## Part 4: Open The Correct Root Folder

The repo has many folders and many modules. You must open the repository root, not `app`, `feature`, `core`, `shared-app` or `iosApp`.

The root folder has files like:

```text
settings.gradle.kts
build.gradle.kts
gradlew
```

If you don't see `settings.gradle.kts`, you are in the wrong folder. Open Android Studio, choose `Open`, pick the repo root and let the IDE import the Gradle project. Only the root folder tells Gradle the full list of modules.

The `iosApp/` folder holds the Xcode project. Android Studio doesn't use it. If you have a Mac, this is the project you open in Xcode to run the iOS build.

## Part 5: Let Gradle Sync Finish

Official docs: [Gradle build lifecycle](https://docs.gradle.org/current/userguide/build_lifecycle.html).

The first sync is slow because Gradle builds a model of the project:

- It reads `settings.gradle.kts` to find the included modules.
- It builds `build-logic/`, which holds the convention plugins shared by every module.
- It reads each module's build file.
- It downloads the Gradle wrapper, plugins and library dependencies (Kotlin Multiplatform, Android Gradle Plugin, Compose Multiplatform, Koin, Ktor...).
- It builds the index Android Studio uses to understand code in `commonMain`, `androidMain` and `iosMain`.

Don't cancel the sync just because the progress bar stops moving. Wait for a clear success or a clear first error. A long stack trace usually has one real cause, near the top.

## Quick Orientation

For now you only need a rough map of what each folder holds.

| Area             | How to read it as a beginner                                  |
| ---------------- | ------------------------------------------------------------- |
| `app`            | Android entry point                                           |
| `iosApp`         | Xcode project, the iOS entry point (not a Gradle module)      |
| `shared-app`     | The app code shared by both platforms: startup, navigation    |
| `feature`        | Screens and user flows                                        |
| `domain`         | Use cases and business rules                                  |
| `data`           | Repository implementations and external services             |
| `core`, `kernel` | Shared technical foundations                                  |
| `theme`          | Design system styling                                         |
| `ui-components`  | Reusable UI building blocks                                   |

## Troubleshooting Table

| Error                                                    | Check first                                                          |
| -------------------------------------------------------- | -------------------------------------------------------------------- |
| Repository page returns `404`                            | Wrong GitHub account, or the invite hasn't been accepted             |
| `Repository not found` when cloning                      | Browser access and the clone URL                                     |
| Authentication keeps prompting                           | `gh auth status` or the Git credential manager                       |
| Android Studio shows no Gradle tasks                     | You opened a nested folder instead of the repo root                  |
| SDK not found                                            | Open the SDK Manager and confirm the SDK location                     |
| Gradle can't download dependencies                       | Network, proxy, VPN or repo access                                   |
| `Cannot find a Java installation ... languageVersion=17` | The machine has no JDK 17. Install JDK 17 and point `JAVA_HOME` at it |
| Plugin version error                                     | Update to the latest stable Android Studio (the repo uses AGP 9)     |
| Missing `google-services.json`                           | Download this file from the Firebase Console into `app/` before a full app build |

## Checkpoint

```bash
git status
```

You are done with this lesson when:

- Android Studio has the repository root open.
- Gradle sync succeeds. If it fails, you have copied the first error and sorted it into one bucket: access, SDK, JDK, network, dependency or missing local config.

---

- Previous lesson: [Install Git, JDK 17, Android Studio And The SDK](https://dantech.academy/en/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-01-install-android-studio-sdk.md)
- Next lesson: [Service Account Checklist](https://dantech.academy/en/courses/kotlin-accelerator/engineer-builder/00-setup-app-running/lesson-03-service-account-checklist.md)