nkapp ci init

Scaffold a CI workflow that deploys your project with Nanokit.

nkapp ci init [--github | --gitlab] [options]

Nanokit is not a CI engine

Nanokit does not ship a pipeline runner, a scheduler, or an approval system. Your existing runner — GitHub Actions or GitLab CI/CD — owns the pipeline; Nanokit is the deploy step inside it (nkapp deploy). ci init scaffolds that wiring for you.

---

Options

Flag	Type	Default	Description
--github	boolean	—	Target GitHub Actions
--gitlab	boolean	—	Target GitLab CI/CD
-e, --env <env>	string	production	Environment the workflow deploys
-b, --branch <branch>	string	main	Branch whose pushes trigger the deploy
-o, --output <path>	string	per provider	Override the output file path
-y, --yes	boolean	false	Overwrite an existing file (by default the command refuses)

Passing both --github and --gitlab is an error.

Provider detection

If neither flag is passed, the provider is auto-detected from the git remote (github.com → GitHub, gitlab.com → GitLab), falling back to a deploy.repository entry in nanokit.yml. If neither resolves, the command exits with an actionable error asking you to pass the flag explicitly.

Output

Provider	Path
GitHub	.github/workflows/nanokit-deploy.yml
GitLab	.gitlab-ci.yml

---

The generated workflow

Self-contained — it depends on no published action or component:

name: Nanokit Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production        # GitHub Environment -> required reviewers = approval gate
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @nkapp/cli
      - run: nkapp deploy -e production -y
        env:
          NANOKIT_TOKEN: ${{ secrets.NANOKIT_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

The GitLab variant is the equivalent job on node:20, gated by a $CI_COMMIT_BRANCH rule and bound to a GitLab Environment.

Approval gates come from your provider

The job binds to environment: <env>, which maps to GitHub Environments / GitLab Protected Environments. Configuring required reviewers there is what gates the deploy. Nanokit deliberately does not build a parallel approval system.

---

CI secrets to set

Secret	Purpose
NANOKIT_TOKEN	Your Nanokit account API key — create one with nkapp auth token create
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	AWS targets
DIGITALOCEAN_TOKEN	DigitalOcean targets
GOOGLE_APPLICATION_CREDENTIALS	GCP targets
AZURE_CLIENT_ID / AZURE_CLIENT_SECRET / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID	Azure targets
CLOUDFLARE_API_TOKEN	Cloudflare DNS

Set only the ones your infrastructure actually uses. After writing the file, the command prints the target path, this checklist, and the next steps.

CI always deploys everything

nkapp deploy is change-proportional based on a local watermark file. An ephemeral runner has no watermark and a fresh checkout rewrites every mtime, so a CI run always resolves to a full deploy. This is by design — see deploy scoping.

---

Reusable artifacts

For teams that prefer an include: / uses: over an inlined workflow, the repository also ships a composite GitHub Action (templates/ci/github/action.yml) and a GitLab CI/CD Catalog component (templates/ci/gitlab/template.yml), both wrapping the same npm i -g @nkapp/cli → nkapp deploy step.

---

Examples

# Auto-detect the provider from the git remote
nkapp ci init

# GitHub Actions, deploying `stage` on pushes to `develop`
nkapp ci init --github -e stage -b develop

# Overwrite an existing workflow
nkapp ci init --github -y