GitPortal - GitHub Deploy Key Setup

GitPortal needs to be able to communicate between repos for CI calls. If you are using GitHub for your repos and GitHub Actions for your CI, These are the steps you’ll need to complete:

• Add a Deploy Key to the KMP repo
• Add a GitHub Actions secret, with the private key for the KMP repo’s Deploy Key, to each app repo

While conceptually simple, this process has several steps that can be brittle and will prevent GitPortal from functioning correctly is not set up properly.

Non-GitHub environments

Touchlab generally uses GitHub for everything. If you are using another environment, you’ll need to adapt these processes for that environment. We would very much welcome documentation submissions to perform this procedure, and will add them to the docs. We’ll add proper credit, of course :)

deploykey command

GitPortal has a convenience command to automate the process, which uses GitHub’s Cli tool. This is the recommended setup procedure.

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

Setup GitPortal CI keys

Call the GitPortal “deploykey” command. You’ll need to supply the KMP repo and the app repos. The KMP repo is supplied with the -k option, and multiple app repos are added with -a arguments.

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.

gitportal deploykey -k [org]/GitPortalTemplateLibrary -a [org]/GitPortalDemoAndroid -a [org]/GitPortalDemoIos

For my personal GitHub org, the command looks like this:

gitportal deploykey -k kpgalligan/GitPortalTemplateLibrary -a kpgalligan/GitPortalDemoAndroid -a touchlab/GitPortalDemoIos

If the deploykey command worked, you’re done! To manually set up deploy keys, see the following section.

Manual Setup

If GitPortal’s deploykey command does not work for some reason, here is the manual setup procedure.

Run the following from a terminal, in a directory that isn’t one of your repos:

ssh-keygen -t ed25519 -f deploykey -C "git@github.com:[ORG]/[KMP REPO]"

Replace [ORG] with your org and [KMP REPO] with the repo of your KMP code. For my personal user example, the call would be:

ssh-keygen -t ed25519 -f deploykey -C "git@github.com:kpgalligan/GitPortalTemplateLibrary"

Note: The -C param is a comment that is usually not important, but it’s critical in this case to set the correct repo info for the KMP repo.

Add your Deploy Key to the KMP repo

Open your browser the GitHub page for the KMP repo. Open “Settings->Deploy Keys”. Create a new Deploy Key, give it a useful name, and make sure to allow write access.

From your local machine, copy the value of deploykey.pub and paste it into the “Key” box. Then click “Add key”.

See screenshot

Add private keys to the app repos

In each of the app repos, Android and iOS, you’ll need to add a GitHub Actions secret with the private key generated with ssh-keygen.

Open your browser to the GitHub page for the Android repo. Go to “Settings > Secrets > Actions”. Click “Add Secret”.

Name the secret GITPORTAL_SSH_KEY.

In the “Secret” text area, paste the contents of the deploykey file generated by ssh-keygen.

Repeat the same process in the iOS repo.