Part 1: Repo and CI Setup

This tutorial series will create a KMP repo and two app repos, one for Android and one for iOS. We’ll add the KMP code to each app repo with GitPortal, and walk through how to use GitPortal to share KMP code with your app repos.

Part 1 of the tutorial will add the repos, and configure CI to communicate between them. We’ll set up the app projects, and walk through using GitPortal in later parts of the tutorial.

Requirements

We’ll be creating GitHub repos. You’ll need a GitHub account, and admin access to the org you want to create the repos in.

For this tutorial, since we’re just demoing the features of GitPortal, you can use your personal account “org” username if you don’t have admin access to another org.

Replace GitHub org value

If you enter your GitHub org into the box below, the page will replace the calls you need to make with your GitHub org, so you can simply copy the command values. Otherwise, replace the GithubOrg string with your org name in the relevant commands.

Type your GitHub org name into this text box and hit “Enter” or click “Replace Values”. If you want to change the value, refresh the page and try again.

Summary of steps

We’ll be:

• Creating three repos from our repo templates. A KMP code repo, and two native app repos.
• Linking the app repos to the KMP repo using GitPortal.
• Configuring the repos so that CI can communicate between them.

Install the GitHub CLI tool

Install the GitHub CLI tool. You can use homebrew to do this:

brew install gh

If newly installed, you’ll need to authenticate the GitHub CLI tool with GitHub:

gh auth login

Some users have reported issues with the gh command after install. You may need to reopen your terminal.

Create the template repos

For this tutorial we’ll need to first create three repos from our templates: A KMP source repo and two app repos. One for Android and one for iOS.

To automate that process with the GitHub CLI tool, run the following:

gh repo create "githubOrg/GitPortalTemplateLibrary" --private -p touchlab/GitPortalTemplateLibrary
gh repo create "githubOrg/GitPortalDemoAndroid" --private -p touchlab/GitPortalDemoAndroid
gh repo create "githubOrg/GitPortalDemoIos" --private -p touchlab/GitPortalDemoIos

To create them manually, open the template repos from your browser and create your repos from the templates directly.

Clone the template repos

Clone the created GitHub repos to your local machine.

With GitHub CLI

gh repo clone https://github.com/githubOrg/GitPortalTemplateLibrary.git
gh repo clone https://github.com/githubOrg/GitPortalDemoAndroid.git
gh repo clone https://github.com/githubOrg/GitPortalDemoIos.git

git clone https://github.com/githubOrg/GitPortalTemplateLibrary.git
git clone https://github.com/githubOrg/GitPortalDemoAndroid.git
git clone https://github.com/githubOrg/GitPortalDemoIos.git

Install GitPortal

To install GitPortal, run the following from a terminal:

brew tap touchlab/homebrew-gitportal
brew install gitportal

If you already have GitPortal installed, check the version with gitportal -v. Make sure it is the latest version 0.7.24. If you need to upgrade, run the following:

brew upgrade gitportal

Link repos with GitPortal

Next, we’ll “link” the KMP code with our app code. GitPortal directly copies the KMP code from the KMP repo into our app repos, along with tracking and version information that GitPortal uses for syncing.

When each command is run, a new folder called library will be added, with a full local copy of the KMP code, as well as a file called .gitportal. You’ll need to keep .gitportal in your code (don’t add it to .gitignore), and avoid editing it directly.

Android

In a terminal, cd to the Android app directory. Run the following:

gitportal bidir.setup library --remote https://github.com/githubOrg/GitPortalTemplateLibrary.git \
    --branch main --code android

iOS

Same as Android. In terminal, cd to the iOS dir and run:

gitportal bidir.setup library --remote https://github.com/githubOrg/GitPortalTemplateLibrary.git \
    --branch main --code ios

Setup Arguments

For setup, you pass in the folder (library), the remote KMP library repo URL, as well as a tracking branch and an app code.

The tracking branch is the branch that can be “tracked” to move changes between repos. It should be the same for both apps. This is (likely) a temporary constraint to simplify R&D work.

The app code is used by GitPortal to organize changes in the KMP repo. Changes pushed from either app to the KMP repo are kept in their own parallel branches. When those changes are later “pulled” into the other app, they come from this tracking branch.

The app code can be any valid git reference, but short, readable strings are recommended. In our case, android for the Android app, and ios for the iOS app.

Configure CI

The CI for the app repos needs to be able to talk to the KMP repo. For that we’ll need to set up a GitHub Deploy Key.

GitPortal has a convenience command to handle this for you, which uses the GitHub CLI tool.

Setup GitPortal CI keys

Run the following command:

gitportal deploykey -k githubOrg/GitPortalTemplateLibrary \
        -a githubOrg/GitPortalDemoAndroid -a githubOrg/GitPortalDemoIos

The arguments for that call are -k, which provides the KMP repo, and the two -a arguments, which are the app repos.

The command will create keys, add the Deploy Key to the KMP repo, and add the private key as a GitHub Actions secret to each of the app repos.

Your template repos should now be created and configured. If there were issues, please report them to us. For now, you can follow the manual setup process.

Next - Part 2: Android Setup