Onboarding

Getting Started

You've just installed Mainline. Here's how to go from zero to managing your apps in a few minutes.

📱 Welcome screen — setup wizard

Mainline uses a guided setup wizard that walks you through each connection in order. You can also tap any item in the Connections list to handle them in your own order, or skip optional steps and come back to them later from Settings.

What you’ll need

Requirement Where to get it Required?
App Store Connect API key (.p8 file) App Store Connect → Users and Access → Integrations Yes
ASC Key ID Same page, shown next to the key name Yes
ASC Issuer ID Same page, shown at the top of the Integrations tab Yes
GitHub Personal Access Token GitHub → Settings → Developer settings → Personal access tokens Optional (for CI features)
Cert repo + passphrase Your existing fastlane match repo, or a new one you create Optional
Anthropic or OpenAI API key anthropic.com/account or platform.openai.com Optional (for AI features)

Step 1 — Connect App Store Connect

This is the only required step. Everything else is optional.

  1. Open App Store Connect in a browser. Go to Users and Access → Integrations → App Store Connect API.
  2. Create a new API key (or use one you already have). The key needs at least App Manager access. Download the .p8 file — Apple only lets you download it once, so keep it safe.
  3. Note the Key ID and Issuer ID shown on the same page.
  4. In Mainline, tap App Store Connect in the setup wizard. Choose how to provide the key:
    • Upload from files — import the .p8 directly from Files or iCloud Drive, then type in the Key ID and Issuer ID.
    • Import from cert repo — if your .p8 is already stored in a private GitHub repo, Mainline can read and extract it automatically. This path requires a GitHub PAT first (see Step 2).
  5. Tap Continue. Mainline validates the key against App Store Connect and stores it securely in the iOS Keychain.
What is an App Store Connect API key?

App Store Connect API keys let third-party tools (like Mainline) act on your behalf through Apple's official API. They're more secure than username/password because they carry only the permissions you assign and can be revoked individually. The .p8 file is the private key; it's paired with a Key ID and Issuer ID that Mainline uses to sign API requests.

If you use fastlane or other CI tools, you likely already have one. You can reuse the same key — Mainline only reads it to make API calls, it never modifies or shares the file itself.

Which permission level do I need?

App Manager is sufficient for most Mainline features: editing metadata, managing submissions, reading builds and reviews, and working with subscriptions.

Admin is required for a small number of operations, such as creating new bundle IDs, managing certificates, and inviting team members. If you're the account holder, you'll naturally have this.

If you're not the account holder, have the admin create the key with the access level appropriate for your role.

🔑 ASC credentials entry screen

Step 2 — Connect GitHub (optional)

Connecting GitHub unlocks CI features: triggering workflows, monitoring run logs in real time, and writing the signing secrets your pipelines need.

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens (or classic tokens).
  2. Create a token with the repo and workflow scopes. Fine-grained tokens: grant read/write access to Actions and Secrets on the repositories you want to manage.
  3. In Mainline, tap GitHub in the setup wizard, paste your token, and tap Validate & Save. Mainline checks the token against the GitHub API and stores it in the Keychain.
What scopes does Mainline need?

Mainline needs repo to read your repositories and the cert repo, and workflow to trigger and read GitHub Actions runs. If you use fine-grained tokens, grant equivalent permissions on the specific repositories you want Mainline to manage.

Mainline never modifies your source code. The only writes it makes to GitHub repos are: (a) updating secrets used for signing, and (b) writing to the cert repo when you sync certificates or profiles.

Step 3 — Connect a cert repo (optional)

A cert repo is a private GitHub repository that stores your code-signing certificates (P12 files) and provisioning profiles in encrypted form. Mainline supports two formats:

  • fastlane match repos — if you already use fastlane match, point Mainline at that repo and give it your MATCH_PASSWORD.
  • Custom (BYO) repos — Mainline’s own format, compatible with openssl enc-encrypted files.
  1. In Mainline, tap Certificates Repo in the setup wizard. (You need a GitHub PAT connected first.)
  2. Pick a repo from the list of your GitHub repositories.
  3. Enter the repo encryption passphrase. This is not your GitHub password — it's the passphrase used to encrypt files inside the repo (your MATCH_PASSWORD for fastlane match, or the passphrase you used with openssl enc). Leave it empty for plaintext repos.
  4. Tap Continue. Mainline auto-detects the repo format and encryption scheme, then stores the configuration.
💡
No cert repo yet?

You can skip this step and set it up later from Settings → Cert Repo. Mainline can manage your app metadata, builds, and submissions without a cert repo — you'll just need one when you want Mainline to inject signing credentials into your CI pipeline.

Supported encryption schemes:

Scheme Description
Plaintext Raw files, private-repo access only
AES-256-CBC + EVP_BytesToKey fastlane match style
AES-256-CBC + PBKDF2 Modern openssl / Mainline custom format

Not supported: GPG, SOPS, age, git-crypt. Convert to one of the above first.

Step 4 — Sync certificates to Keychain (optional)

After configuring the cert repo, Mainline offers to pull your team’s distribution certificates and provisioning profiles from ASC and your repo into the device Keychain. This means your first CI build won’t need a re-fetch.

You can do this now or skip it — the Sync button on the Dashboard does the same thing at any time.

Step 5 — Connect an AI provider (optional)

Connecting an AI provider unlocks AI-assisted features: translation, metadata drafting, and review-reply suggestions. You can use Anthropic (Claude) or OpenAI (ChatGPT), or both.

  1. Get an API key from console.anthropic.com or platform.openai.com.
  2. In Mainline, tap AI Provider in the setup wizard and paste your key(s).
  3. Tap Save. You can change provider and model any time in Settings → AI Provider.
ℹ️
AI is always human-in-the-loop

Every piece of AI-generated content — translations, drafted descriptions, reply suggestions — is shown to you for review before anything is sent to App Store Connect. Mainline never writes AI content directly to ASC.

You’re set up — what’s next?

Once App Store Connect is connected, tap Continue to Dashboard. You’ll see all your apps pulled from ASC.

From here, explore the features you need most:

Free vs Pro

Mainline is free to use with one pinned app. The free tier includes all features — there are no feature-level restrictions, only an app-count limit.

Free tier

  • One app pinned — you choose which app to manage. All features available for that app.
  • Read-only for other apps — you can browse your other apps but cannot make changes.
  • Re-pin with a cooldown — you can change your pinned app, but there’s a 90-day waiting period between re-pins. This is to prevent the free tier from being equivalent to a Pro subscription.

Mainline Pro

  • Unlimited apps — full read and write access for every app in your ASC account.
  • Billed monthly or annually via in-app purchase.

Pinning an app

When you first open the Dashboard, Mainline automatically pins your first app if you only have one. If you have multiple apps, you’ll be prompted to choose one to pin.

The 90-day re-pin cooldown

If you want to switch your pinned app, you can do so from Settings → Plan. The cooldown timer starts from the last time you pinned an app. If you’re within the cooldown window, the re-pin option shows how long is left.

💡
Just one app?

If your ASC account only has one app, you never hit the free-tier limit in practice — read and write access is always on for your sole app.