· 4 min read Posted by Kevin Galligan

GitPortal for KMP Tutorial

Part 1: Repo and CI Setup

For teams piloting KMP, direct access to the Kotlin source is the best way to get started. Use GitPortal to link and sync KMP source from an external repo. In Part 1, we'll install GitPortal, set up the three source code repos, and configure CI to monitor everything.

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.

Read more about KMP strategies for native mobile teams in Touchlab’s KMP For Teams Guide.


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”.

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

GitHub Cli Tool

We’ll be using the GitHub Cli tool to automate some of the tedious manual steps. If you’d prefer to do everything manually, see the GitPortal Docs

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

Reopen terminal

You may need to reopen your terminal to have gh in your path. If you get errors with gitportal calls, try reopening you terminal.

Create the template repos

For this tutorial we’ll need to first do the following:

  • Create three repos from our templates: A KMP source repo and two app repos, one for Android and one for iOS
  • Create a GitHub Release in the KMP repo (we need tags for GitPortal, and GitHub Releases also create tags)

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

gh release create "0.1.0" -R "githubOrg/GitPortalTemplateLibrary" -t "0.1.0" -n "Tutorial release" --latest

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
With 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

Manually githubOrg/GitPortalTemplateLibrary



First, install GitPortal. Run the following from a terminal:

brew tap touchlab/homebrew-gitportal
brew install gitportal

If you are not using a mac, or don’t use Homebrew, see the GitPortal docs for alternative installation methods.


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

gitportal setup library -r https://github.com/githubOrg/GitPortalTemplateLibrary.git -t 0.1.0


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

gitportal setup library -r https://github.com/githubOrg/GitPortalTemplateLibrary.git -t 0.1.0

Configure CI

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

GitPortal has a convenience command to handle this for you. You’ll need to install the GitHub Cli tool and authenticate that tool with GitHub. However, this option is much easier than setting everything up manually.

Setup GitPortal CI keys

In your terminal, cd to the local KMP repo. It should be cloned from githubOrg/GitPortalTemplateLibrary.

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 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 use. For now, you can follow the manual setup process.

Next - Part 2: Android Setup