Skip to main content

Automate App Onboarding with gap-api

Deploying your first application to GAP touches several repositories: your app repo, a shared credentials repo, your team's Kubernetes manifests repo, and the Argo CD repo. gap-api is a tool that automates this setup for you, so you don't have to make each change by hand.

This guide explains what gap-api does and how to use it. If you'd rather understand or perform the underlying steps yourself, see Deploy Your First App using Gappynator and Argo CD — the two guides describe the same process, one automated and one manual.

Early access

gap-api is under active development. It currently supports Spring Boot applications only, and the flow is still being validated across different repository setups. If a step doesn't work as expected, fall back to the manual guide for that step and reach out in #gap.

What gap-api does​

Given some basic information about your team and application, gap-api walks through the same steps described in the manual guide:

  1. Create a GitHub repository for your app (optional, if you don't already have one)
  2. Request access to push container images to the shared registry
  3. Request a token so your workflow can update your Kubernetes manifests
  4. Add a GitHub Actions workflow to your app repo that builds and publishes your container image
  5. Add Kubernetes manifests for your application to your team's manifests repo
  6. Add an Argo CD application definition so your app gets deployed and kept in sync

Changes to shared or protected repositories are made as pull requests, so a human always reviews them before anything is merged — gap-api never merges on your behalf. It's also safe to run more than once: any step whose result already exists is simply skipped.

Some steps need to wait for a pull request to be merged (and, in a couple of cases, for the platform team to apply the change) before the next step can continue. gap-api tracks this for you and lets you pick up where you left off.

Before you start​

  • Your team must already be onboarded to GAP, with a Kubernetes namespace set up — see Namespace Onboarding.
  • If your application depends on Azure resources such as a database, those are provisioned separately, before you onboard the application itself — see Provision Resources. gap-api does not create or manage Azure resources; it only wires up how your application gets built and deployed.
  • You'll need access to the repositories involved (your app repo and your team's manifests repo).

How to use it​

gap-api is used through a command-line tool called gap.

1. Preview what will be created​

Before making any real changes, you can preview exactly what gap-api would generate — this runs entirely on your machine and doesn't touch GitHub:

gap preview \
  --team <your-team> \
  --team-code <your-team-code> \
  --app <your-app> \
  --manifest-repo <your-team>-kubernetes-manifests \
  --cost-center <your-cost-center> \
  --service-code <your-service-code> \
  --env test,prod

This prints the generated workflow and manifest files so you can review them before proceeding. Add --output ./preview-output to write them to a folder instead.

2. Run onboarding​

Once you're happy with the preview, start the guided setup:

gap init

This launches an interactive wizard that asks for your team, app, and environment details, then works through the steps one by one. Whenever a step opens a pull request, gap init shows you the link and pauses — review and merge it, then continue.

3. Track and resume​

You can check on an onboarding at any time, and pick it back up after merging a pending pull request:

gap status <session-id>   # see what's done, waiting, or still to do
gap resume <session-id>   # continue from where you left off
gap list                  # see all of your onboarding sessions

After onboarding​

Once all steps are complete, Argo CD will pick up your new application and start syncing it to your cluster. Follow the "Verify Application is Running" section of the manual guide to confirm your app is healthy.

Learn more​