Skip to main content

Auto CI Setup

Manually building and deploying every time you push code is tedious and error-prone. With Auto CI, builds and deployments start automatically the moment you push code to GitLab. Set it up once, and you can focus entirely on development.

Why use Auto CI?
  • Save time: No more waiting to manually trigger builds and deployments .
  • Prevent mistakes: Reduce human errors that occur during manual deployment .
  • Maintain consistency: Builds and deploys the same way every time
  • Fast feedback: See results immediately after pushing code .

Auto CI Settings Modal

Overview​

Auto CI detects GitLab Webhook events and automatically runs the build pipeline. Here's the complete flow:

graph LR
    A[GitLab Push] --> B[Webhook Trigger]
    B --> C[KIWI Build Start]
    C --> D[Kaniko Build]
    D --> E[Harbor Push]
    E --> F[Auto Deploy]

Supported Events​

You can automatically start builds in response to various Git events:

  • Push: Triggered when a commit is pushed to a branch. Use for development branch auto-build and continuous integration.

  • Merge Request: Triggered when an MR is created or updated. Use for build verification before code review.

  • Tag: Triggered when a tag is created. Use for release version builds.

  • Pipeline: Triggered when GitLab CI completes. Use for integration with existing GitLab CI results.

Prerequisites​

The following conditions must be met before setting up Auto CI:

Pre-setup Checklist

If any of the items below are missing, the Auto CI button will be disabled. Complete all items first.

  • Service registered (required): Service must be registered on the [Service Management] page
  • GitLab token configured (required): GitLab Access Token must be entered in service settings .
  • Registry configured (required): Harbor/DockerHub registry information must be entered in service settings .
  • Dockerfile present (recommended): If not available, auto-generate with Build Wizard
  • K8s cluster connected (required for auto-deploy): Cluster must be registered in [Runtime Environment]
Button disabled?

If the Auto CI button appears grayed out, check the service detail page for missing settings. Usually it's the GitLab token or Registry settings that are missing.

Step 1: Open the Auto CI Settings Modal​

1.1 Access from Service List​

  1. Navigate to the [Service Management] page (/services)
  2. Find the service to configure Auto CI for
  3. Click the Lightning icon (Auto CI) button on the right side of the service card
Can't find the icon?

The lightning icon is located at the top right of the service card. Hover over it to see the "Auto CI" tooltip.

1.2 Access from Pipeline View​

You can also access it from the 4-stage pipeline displayed on the service card:

  • Source: Click to check GitLab integration status.

  • Build: Click to open build settings and Auto CI modal.

  • Deploy: Click to view deployment settings.

  • Operate: Click to monitor deployed service.

Click the Build stage in the pipeline to access build-related settings.

Step 2: Basic Settings (Settings Tab)​

When the Auto CI modal opens, the basic settings tab is displayed. This is where you configure the core Auto CI options.

2.1 Enable Auto CI​

  • Enable Auto CI: Toggle switch to turn the Auto CI feature on/off

    • Recommended: ON (activate right after initial setup)

  • Git Branch: Select the branch to detect Webhooks on

    • Development environment: develop branch recommended .
    • Production environment: main or master branch recommended .
Branch Selection Note

Selecting all branches (*) will trigger builds on every feature branch push, which can waste resources. Choose specific branches when possible.

Branch Strategy by Environment
  • Development: Use develop branch with Auto Deploy ON for fast feedback.
  • Staging: Use main branch with Auto Deploy ON to verify latest versions.
  • Production: Use main branch + tags with Auto Deploy OFF. Manual approval is recommended for production deployments.

2.2 Registry Information Check​

Registry information entered during service registration is automatically displayed. This is where your built images will be stored.

  • Registry URL: Registry address where images are stored (e.g., harbor.mipllab.com)
  • Registry Type: Type of registry (Harbor or Docker Hub)
  • Project/Namespace: Image storage location (e.g., library, myproject)
  • Image Name: Name of the image to build (default: same as service name)
Registry information not showing?

If registry information is not displayed, you need to complete Registry Settings first on the service detail page. Click the service card to go to the detail page and check the settings.

Step 3: Detect Build Target Services​

KIWI analyzes your Git repository and automatically detects project information. This step helps identify Dockerfile locations and project structure.

3.1 Auto-detect Project Type​

  1. Click the Detect Services button .
  2. KIWI analyzes the Git repository and automatically detects project information (usually takes a few seconds)
Why is detection needed?

Build methods differ depending on project type. For example, Node.js projects install dependencies with npm install, while Python projects use pip install. KIWI automatically identifies this and suggests optimal build settings.

3.2 Detection Result Fields​

When detection is complete, the following information is displayed:

  • Language: Programming language used (e.g., Node.js, Java, Python, Go).

  • Framework: Framework used (e.g., React, Spring Boot, Django).

  • Package Manager: Package management tool (e.g., npm, yarn, Maven, pip).

  • Build Type: Repository structure (Single-repo or Mono-repo).

  • TypeScript: Whether TypeScript is used (Yes or No).

  • Dockerfile: Dockerfile location (e.g., ./Dockerfile, ./docker/Dockerfile).

3.3 Handling Monorepo Projects​

What is a monorepo?

A monorepo is a structure where multiple projects (frontend, backend, etc.) exist together in a single Git repository. It's used in large projects to make code sharing and version management easier.

For monorepo projects, multiple services are detected:

  1. A table of detected sub-project list is displayed .
  2. Select sub-projects to build using checkboxes
  3. Verify/modify the Dockerfile path for each project

Typical monorepo structure example:

my-project/
├── frontend/         → Image: my-project-frontend
│   └── Dockerfile
├── backend/          → Image: my-project-backend
│   └── Dockerfile
└── api-gateway/      → Image: my-project-gateway
    └── Dockerfile
Monorepo build tip

Builds run in parallel for each selected sub-project. In resource-constrained environments, adjust the number of projects to build at once.

Step 4: Registry Secret Setup​

To pull images from a Private Registry (e.g., Harbor) in Kubernetes, authentication credentials are required. KIWI automatically creates these credentials as a Kubernetes Secret.

What is a Registry Secret?

Pulling images from a Private Registry (Harbor, private Docker Registry, etc.) requires login credentials. Kubernetes stores these login credentials in a resource called Secret, and uses this Secret when creating Pods to pull images.

4.1 Check if Secret Exists​

  1. Click the Check Secret button .
  2. One of the following is displayed based on the result:
    • "Secret already exists" - Already created. Proceed to the next step.
    • "Secret not found" - You need to create the Secret.

4.2 Auto-create Secret​

If no Secret exists, KIWI will create it automatically:

  1. Click the Create Registry Secret button .
  2. KIWI creates the Secret in the K8s cluster .
  3. Verify the "Secret created successfully" message

Created Secret information:

  • Secret name: {serviceName}-registry-cred

  • Namespace: Service deployment namespace (default: service name)

  • Type: kubernetes.io/dockerconfigjson

  • Contents: Registry credentials (username, password)

4.3 Recreate Secret (When Password Changes)​

If the registry password has changed or you need to update the Secret:

  1. First delete the existing Secret from the K8s cluster .
  2. Create a new one using the Create Registry Secret button .
If Secret Creation Fails

If Secret creation fails, check the following:

  • Is the K8s cluster connection working?
  • Do you have Secret creation permissions (RBAC) for that namespace?
  • Does the namespace exist?

If it's a permission issue, request create permission for secrets resources from the cluster administrator.

Step 5: Webhook URL and Secret Token Setup​

In this step, you'll configure the Webhook so that GitLab can send events to KIWI. This connection enables automatic builds when code is pushed.

What is a Webhook?

A Webhook is a way to send a notification to a specified URL when a specific event (e.g., code push) occurs. When code is pushed to GitLab, a notification saying "new code was pushed!" is sent to KIWI's Webhook URL, and KIWI receives it to start the build.

5.1 Understanding Environment-specific Webhook Settings​

KIWI provides different Webhook URLs for each environment. Choose the URL that matches your current environment.

  • Local: For local development using ngrok tunnel. Example: https://xxx.ngrok.io/api/v1/webhook/gitlab

  • Dev: For development server. Example: https://dev.example.com/api/v1/webhook/gitlab

  • Staging: For staging environment. Example: https://staging.example.com/api/v1/webhook/gitlab

  • Production: For production environment. Example: https://kiwi.example.com/api/v1/webhook/gitlab

5.2 Copy Webhook URL​

  1. Find the environment you want to use in the Webhook Environments section .
  2. Click the Copy URL button to copy the Webhook URL
  3. Click the Copy Token button to copy the Secret Token as well

5.3 Register Webhook in GitLab​

Now register the copied information in your GitLab project.

Step-by-step guide:

  1. Go to your GitLab project page

  2. Click Settings → Webhooks in the left menu

  3. Enter the following information:

    • URL: Webhook URL copied from KIWI
    • Secret token: Secret Token copied from KIWI

  4. In the Trigger section, select events:

    • ✅ Push events (required)
    • ✅ Merge request events (recommended)
    • ✅ Tag push events (for release builds)

  5. SSL verification: ✅ Check Enable SSL verification (recommended)

  6. Click the Add webhook button .

Secret Token Security

The Secret Token is unique per service, and if exposed, malicious build triggers can occur. Never expose it in public repositories or documentation.

Webhook Test

After registering the Webhook in GitLab, you can click the Test button to test the connection. If you see "Hook executed successfully", it's working correctly.

Step 6: Event Settings​

Configure which Git events should trigger builds. You can combine multiple events as needed.

6.1 Select Trigger Events​

  • Push: Builds when code is pushed to the specified branch. Recommended for continuous integration and development branch auto-build.

  • Merge Request: Builds when MR is created, updated, or merged. Recommended for build verification before code review.

  • Tag: Builds when a tag is created. Recommended for release version builds.

Event Combination Examples
  • Development environment: Push events only (fast feedback)
  • Staging environment: Push + MR events (verification before merge)
  • Production environment: Tag events only (build only release versions)

6.2 Branch Filtering​

You can filter builds to run only on specific branches:

  • main: Matches main branch only.

  • develop: Matches develop branch only.

  • feature/*: Matches all branches starting with feature/.

  • release/*: Matches all branches starting with release/.

  • *: Matches all branches (not recommended due to resource waste).

Building All Branches Warning

Using the * pattern will trigger builds on every feature branch push. The build queue fills up quickly and resources can be wasted, so choose carefully.

6.3 Auto Deploy Settings​

Configure whether to automatically deploy after a successful build. We recommend auto-deploy for development/staging environments and manual deploy for production.

  • Auto Deploy: Enable/disable automatic deployment on build success .
  • Deploy Environment: Select target deployment environment (K8s namespace)
Auto Deploy vs Manual Deploy
  • Development: Auto Deploy ON. Fast feedback is needed for rapid iteration.
  • Staging: Auto Deploy ON. Latest version verification is needed continuously.
  • Production: Auto Deploy OFF. Careful, controlled deployment is needed for stability.

Step 7: Save Settings and Test​

Once configuration is complete, let's save and test. Testing ensures all connections are working properly.

7.1 Save Settings​

  1. Review all settings .
  2. Click the Save button .
  3. Verify the "Auto CI settings have been saved" message

7.2 Test Webhook​

Before pushing actual code, verify the connection using GitLab's test feature:

  1. Go to GitLab project → Settings → Webhooks
  2. Find the registered Webhook entry .
  3. Click the Test dropdown button .
  4. Select Push events
Test Result Check
  • Hook executed successfully: HTTP 200 - Connection is working .
  • HTTP 401/403 - Secret Token mismatch or permission issue
  • Connection failed - Cannot access KIWI server (check firewall, URL errors)

7.3 Verify Build in KIWI​

After sending the test event, verify in KIWI:

  1. Navigate to the [Service Management] page
  2. Check if the Build stage in the service pipeline shows "Building" status .
  3. Click to verify the "Triggered by Webhook" message in the build log

7.4 Monitor Build Progress​

Once the build starts, you can monitor progress in real time:

  • Progress Bar: Shows build progress from 0 to 100%.

  • Current Step: Shows the currently running stage (Clone, Build, Push, etc.).

  • Build Log: Displays real-time build log with terminal output.

  • Duration: Shows build elapsed time.

Reducing Build Time

The first build may take longer as there's no image cache. From the second build onwards, it completes quickly by utilizing cache.

Real-world Usage Scenarios​

Here are Auto CI configuration examples for various team workflows. Refer to the scenario that matches your situation.

Scenario 1: Development Branch Auto Build/Deploy​

Situation: Developers want code pushed to the develop branch to be automatically deployed to the dev server for immediate verification.

Configuration:

  • Auto CI: Enabled
  • Git Branch: develop
  • Trigger Events: Push events .
  • Auto Deploy: Enabled
  • Deploy Environment: dev

Result: Pushing to develop branch automatically builds and deploys to development environment.

Scenario 2: Release Tag Build​

Situation: You want to build production images only when creating release tags like v1.0.0, and deploy manually.

Configuration:

  • Auto CI: Enabled
  • Trigger Events: Tag push events .
  • Auto Deploy: Disabled

Result: Running git tag v1.0.0 && git push --tags automatically builds, and deployment is done separately.

Scenario 3: MR Validation Build​

Situation: You want to automatically verify that builds succeed before code review.

Configuration:

  • Auto CI: Enabled
  • Trigger Events: Merge request events .
  • Auto Deploy: Disabled

Result: Builds run automatically when MRs are created/updated, preventing merges if builds fail.

Practical Tip

Many teams combine Scenario 1 (development environment) and Scenario 2 (production environment). Development is automatic, production is careful!

Troubleshooting​

If you encounter issues during Auto CI setup or builds, refer to the guide below.

Webhook Not Triggering​

  • "Connection refused" in GitLab test: Cannot access KIWI server. Check firewall settings and verify KIWI server status.

  • "HTTP 401/403" in GitLab test: Secret Token mismatch. Copy token again from KIWI and re-register in GitLab.

  • Test succeeded but no build: Branch filter issue. Verify the pushed branch matches Auto CI branch settings.

  • Only certain events don't work: Event setting may be missing. Verify the event is enabled in KIWI Auto CI modal.

Debugging Tip

Check Recent Deliveries in GitLab's Settings → Webhooks to see the request/response content of each Webhook call.

Registry Secret Creation Failure​

  • "Permission denied": Insufficient K8s permissions. Request secrets resource create permission from cluster admin.

  • "Namespace not found": Namespace doesn't exist. Create the namespace first or select a different namespace.

  • "Secret already exists": Existing Secret is present. Delete the existing Secret and recreate.

Build Failure​

  • "Dockerfile not found": No Dockerfile in the repository. Generate a Dockerfile with Build Wizard.

  • "Build timeout": Build time exceeded the limit. Increase build resources or optimize Dockerfile.

  • "Registry authentication failed": Registry auth failed. Re-verify registry credentials (username/password).

  • "Git clone failed": Git access failed. Verify GitLab token has read_repository permission.

Build Stuck in Pending​

  • Cause: Reached concurrent build limit or insufficient build workers .
  • Solution: Wait for previous builds to complete, or cancel unnecessary builds .
  • Note: If building status persists for more than 5 minutes, it will automatically be marked as failed .
When to Contact Administrator
  • When builds repeatedly timeout (resource increase needed)
  • When Registry Secret permission issues aren't resolved .
  • When Webhook URL is not accessible from external networks .

Reference: Build System Architecture​

                    ┌─────────────┐
                    │   GitLab    │
                    │   Server    │
                    └──────┬──────┘
                           │ Webhook (Push/MR/Tag)
                           ▼
                    ┌─────────────┐
                    │    KIWI     │
                    │   Backend   │
                    └──────┬──────┘
                           │ Build Queue
                           ▼
┌─────────────────────────────────────────────┐
│              Build Queue Worker             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │ Build 1 │  │ Build 2 │  │ Build 3 │ ... │
│  └────┬────┘  └────┬────┘  └────┬────┘     │
└───────┼────────────┼────────────┼──────────┘
        │            │            │
        ▼            ▼            ▼
┌─────────────────────────────────────────────┐
│           Kubernetes Cluster                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │ Kaniko   │ │ Kaniko   │ │ Kaniko   │    │
│  │ Pod 1    │ │ Pod 2    │ │ Pod 3    │    │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘    │
└───────┼────────────┼────────────┼──────────┘
        │            │            │
        └────────────┼────────────┘
                     ▼
              ┌─────────────┐
              │   Harbor    │
              │  Registry   │
              └─────────────┘