SimpleCI

SimpleCI is a lightweight, self-hosted continuous integration (CI) application designed to replace complex tools like Jenkins with a streamlined, modern alternative. Built entirely in Go, it leverages templ for server-side rendering and HTMX for dynamic, interactive UI updates without heavy JavaScript frameworks. SimpleCI focuses on simplicity, security, and ease of use, allowing you to define pipelines that run on remote agents via SSH.

Overview

SimpleCI consists of a central controller (the web app) that manages credentials, agents, and pipelines. Pipelines are defined in YAML and executed on agents; remote machines you connect to via SSH using stored credentials (private keys). The controller triggers builds on events like Git pushes (via webhooks) and provides a real-time dashboard for monitoring.

Key goals:

• Minimal dependencies and easy deployment as a single cross-compilable binary.
• Secure credential management with encrypted storage.
• Pipelines with simple syntax for stages containing multiple steps.

Features

• Credential Management: Store SSH private keys securely for authenticating to agents.
• Agent Orchestration: Register remote machines as build agents; the controller uses SSH to connect to them to run pipelines.
• Pipeline Definition: YAML-based pipelines with stages, steps, and artifacts are read from your git repository.
• Scheduling: Schedule pipelines to run using cron scheduling expressions for a specified branch.
• Web Dashboard: Intuitive UI powered by templ and HTMX for creating/editing resources and viewing build logs in real-time.
• Webhook Integration: Trigger builds from GitHub/GitLab on push or PR events.
• Artifact Storage: Download build artifacts directly from the UI.

Technology Stack

• Backend: Go (100% Go codebase for the controller and agent runner).
• Templating: github.com/a-h/templ for type-safe HTML components.
• Frontend Interactivity: HTMX for AJAX-driven updates without a build step.
• Database: SQLite.
• Networking: SSH for agent communication; HTTP/HTTPS for the web interface.

No Node.js, no Docker required. Just deploy as a single binary.

Quick Start

Prerequisites

• Go 1.21 or later.
• A remote machine (agent) with SSH access.

Installation

1. Clone the repository:

   git clone https://github.com/haatos/simple-ci.git
   cd simple-ci
   

2. Build the binary:

   go build -o simpleci ./cmd/simpleci/main.go
   

3. Run the controller:

   ./simpleci
   

   The web UI will be available at http://localhost:8080.

Configuration

Use environment variables or a .env file for setup:

• SIMPLECI_HASH_KEY: Encryption key, 32 bytes. This is automatically generated, and saved into .env, if not found.
• SIMPLECI_BLOCK_KEY: Block key, 24 bytes. This is automatically generated, and saved into .env, if not found.
• SIMPLECI_DB_PATH: Path to SQLite DB (default: ./db.sqlite).
• SIMPLECI_PORT: HTTP listen port (default: 8080).

Configure maximum run queue size and authentication session validity in hours with a config.json file in the same directory as the application:

{
  "session_expiration_hours": 720,
  "queue_size": 3
}

This file is generated automatically at application start if it does not already exist.

For production, use a reverse proxy like Caddy or Nginx for HTTPS.

Agent setup

1. Generate an SSH key on your the controller (machine running the application). ssh-keygen -t rsa
2. Append the public key ~/.ssh/id_rsa.pub contents to the ~/.ssh/authorized_keys file on the agent machine.
3. Ensure the authorized keys file has the correct permissions on the agent: chmod 600 ~/.ssh/authorized_keys

Usage

Creating Credentials

1. Navigate to Credentials page from the side menu or home page.
2. Click 'Add credential'.
3. Fill in the form: username, description (optional) and SSH private key (PEM format).
4. Click 'Add'.
5. The key is encrypted at rest using your SIMPLECI_SECRET_KEY.

Credentials are referenced in agent configurations.

Setting Up Agents

1. Navigate to Agents page from the side menu or home page.
2. Click 'Add agent'
3. Fill in the form: select a credential, name, hostname (for SSH including port, defaulting to 22 if omitted), workspace and description (optional).
4. Click 'Add'
5. Click the 'Test connection' button of the Agent to verify it is setup correctly.

Agents run pipelines in isolated workspaces.

Defining Pipelines

1. Navigate to Pipelines page from the side menu or home page.
2. Click 'Add pipeline'.
3. Fill in the form: select an agent, enter a name and description (optional), enter a repository path, enter a script path (path to the pipeline script within the repository).
4. Click 'Add'.
5. Click 'Run pipeline' and fill in branch (git repository branch) to test. You will be navigated to the pipeline run page.

Pipelines should follow the following format:

stages:
  - stage: Test
    steps:
      - step: Run tests
        script: go test ./...
  - stage: Build
    steps:
      - step: Run build
        script: go build -o bin/simpleci cmd/simpleci/main.go
    artifacts: bin

Contributing

1. Fork the repo and create a feature branch (git checkout -b feature/my-feature).
2. Commit your changes (git commit -m 'Add my feature').
3. Push to the branch (git push origin feature/my-feature).
4. Open a Pull Request.

We welcome contributions for new step types, UI improvements, or integrations. Run tests with go test ./....

License

This project is licensed under the MIT License - see the LICENSE file for details.