GitHub Integration

Overview

The Kyper GitHub App connects your GitHub repository to your Kyper app. When you push a semver tag (e.g. v1.2.3), Kyper automatically:

1. Pulls the source from GitHub
2. Validates your kyper.yml
3. Builds the Docker image and runs a security scan
4. Posts a Check Run to the tagged commit with a live build link
5. Emails you to complete the submission (demo env vars for reviewers)

No workflow file is required in your repo. No tokens to manage. The GitHub App handles everything.

Setup

# Install the CLI once
brew tap bitfootco/tap && brew install kyper

# Generate kyper.yml interactively (auto-detects your stack)
kyper init

# Commit it
git add kyper.yml && git commit -m "Add kyper.yml"

git tag v1.2.3
git push origin v1.2.3

Tag format

Tags must be semver with an optional leading v. Clean semver tags (v1.2.3) trigger the standard build + submission flow. Pre-release identifiers (v1.2.3-rc.1) trigger a test deploy — see Test deploys below.

Non-matching tags are silently ignored — they don't cause errors or notifications.

GitHub Check Run

Kyper posts a Check Run to every tagged or branch commit it processes. The check run tracks the full lifecycle — build, security scan, and (for test deploys) provisioning.

Release tags (v1.2.3)

Test deploys (pre-release tags + branch pushes)

All check runs link to the Kyper build tracker for the full live log.

Test deploys

Kyper supports two ways to trigger a test deploy from GitHub — pre-release tags for deliberate checkpoints, and a configured branch for continuous iteration. Both produce a live HTTPS URL on Kyper's real K8s infrastructure that auto-destructs after one hour. No review submission, no marketplace listing.

Option 1 — Test deploy branch (recommended for iteration)

Configure a test deploy branch on your repo link (Developer Portal → your app → GitHub → Settings). Once set, every push to that branch automatically builds a fresh test deploy and destroys the previous one. No tagging required — just push and your live URL updates.

The build is labelled branch-{sha} in the portal (e.g. branch-deadbeef). A Check Run is posted to the commit so you can see build status directly in your GitHub pull request or commit view.

This is the recommended workflow if you're iterating on a feature and want continuous feedback without managing tags. Use main, develop, or any branch name — whatever fits your Git workflow.

Option 2 — Pre-release tags

Push a tag with a SemVer pre-release identifier to trigger a one-off test deploy for a specific checkpoint.

# Test deploy — live HTTPS URL for 1 hour
git tag v1.2.0-rc.1
git push origin v1.2.0-rc.1

# When ready to ship — clean tag triggers full submission
git tag v1.2.0
git push origin v1.2.0

Any pre-release identifier works: -rc.1, -beta, -alpha.2, and so on. GitHub marks these as "Pre-release" in its releases UI automatically.

CLI option

You can also trigger test deploys manually with the CLI: kyper test. This uploads a local zip rather than fetching from GitHub, so it works independently of any repo link.

Env vars for test deploys

GitHub-triggered test deploys run on Kyper's real K8s infrastructure. If your kyper.yml declares a required_env list, those vars must be satisfied or the deployment will fail at provision time.

To provide test credentials, go to Developer Portal → your app → GitHub → Settings and add key/value pairs in the Test deploy env vars section. These values are:

• Encrypted at rest — never stored in plaintext
• Only injected into GitHub-triggered test deploys for this repo link
• Never used for consumer (production) deployments

Use sandbox or test-mode API keys here (e.g. sk_test_… for Stripe). If a required var is missing when a test deploy runs, the GitHub Check Run will fail with the exact variable names and a direct link to the settings page.

Alternatively, you can set vars as publisher env vars on the app — these are injected into all deployments including test deploys. Good for non-secret defaults (e.g. a feature flag or a region name); use repo link test env vars for anything credential-like.

Using the CLI alongside GitHub

The GitHub integration and kyper push produce identical build records — the same pipeline, just different delivery mechanisms. You can use both at the same time. GitHub-triggered builds are labelled in the developer portal.

The CLI is particularly useful for initial project setup (kyper init), local validation (kyper check), and local Docker builds (kyper build).

Optional: auto-tagging on merge

If you want every merge to main to trigger a build automatically (useful for agentic security patches or Dependabot fixes), you can add an auto-tagging workflow to your repo. This is optional — you can always tag manually.

The workflow below uses github-tag-action with conventional commits (fix: → patch, feat: → minor, BREAKING CHANGE → major). No Kyper secrets needed in the workflow.

# .github/workflows/kyper-release.yml
name: Kyper Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Bump version and push tag
        uses: mathieudutour/[email protected]
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          default_bump: patch
          release_branches: main

Save this file as .github/workflows/kyper-release.yml in your repo. Adapt default_bump to your preference (patch, minor, or major).

Migrating an existing app

No data migration needed. Linking a GitHub repository is purely additive — existing versions, build history, and subscriptions are untouched. The next semver tag you push just creates a new version the same way a kyper push would.

1. Install the Kyper GitHub App on your GitHub account or org (one-time)
2. Open each existing app in the developer portal → Connect GitHub → pick the repo
3. Push a new semver tag when you're ready for the next release