Skip to content

feat: enhance docs homepage and readme #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jim-junior merged 1 commit into from
Jun 6, 2026
Merged

feat: enhance docs homepage and readme #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 72 additions & 16 deletions docs/docs/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,32 +14,73 @@ width="200"

</div>

### The Headless Control Plane for Building CI/CD Platforms
---


**A headless workflow orchestration engine for building custom CI/CD, automation, and delivery platforms.**

Conveyor CI is a lightweight control plane for platform teams that want to build their own CI/CD systems, deployment platforms, internal developer platforms, or automation backends.

It is not an all-in-one CI/CD product like Jenkins, GitHub Actions, GitLab CI, or Argo Workflows. Conveyor does not provide a built-in dashboard, hosted runners, or an opinionated execution environment. Instead, it provides the orchestration layer: workflow state, job lifecycle management, event-driven execution, log streaming, and APIs that you can embed into your own platform.

You bring the execution logic. Conveyor manages the orchestration.

## Why Conveyor CI?

Many CI/CD and workflow systems are built as complete platforms. They usually bundle together:

- A user interface
- Pipeline orchestration
- Job scheduling
- Execution environments or runners
- Storage
- Logs
- Authentication and access control
- Infrastructure-specific assumptions

That works well when you want to adopt a complete CI/CD system.

Conveyor CI is designed for a different use case: building your own platform.

It gives platform developers a small, embeddable orchestration core that can be connected to custom execution environments through drivers. This makes it useful when you need full control over where workloads run, how they run, and how the developer experience is exposed.

Conveyor CI is not a CI tool. It is a control plane for building CI systems. If Jenkins and GitHub Actions are “all-in-one” platforms, Conveyor CI is the orchestration engine underneath them minus the UI, minus opinionated runners, minus infrastructure lock-in. You don’t use Conveyor to run `go build`. You use Conveyor to build a system that runs `go build` for thousands of users.
## Use Cases

## Who Is This For?
Conveyor CI is designed for platform builders, infrastructure teams, and product teams building automation into their own systems.

Conveyor CI is built for _platform engineers_ and SaaS builders, not end users. It is ideal for:
Common use cases include:

* Internal Developer Platforms (IDPs) embedding CI/CD capabilities
* SaaS products offering “Deploy”, “Build”, or “Automation” features
* Edge & air-gapped environments requiring custom execution logic
* Organizations with strict security or infrastructure control needs
- Internal Developer Platforms that need custom build and deployment workflows
- PaaS platforms that provide “deploy from Git” or “build from source” features
- SaaS products that need background job orchestration or task execution
- Custom CI/CD platforms with organization-specific execution rules
- Edge, IoT, or air-gapped environments where standard CI/CD systems are too heavy or too restrictive
- Systems that need to orchestrate jobs across Kubernetes, bare metal, virtual machines, or custom infrastructure

If you need complete control over where and how workloads execute, Conveyor is for you.
## Project Status

## Architecture: Control Plane vs Execution
Conveyor CI is under active development.

Conveyor CI enforces a strict architectural boundary.
The project currently focuses on the core orchestration runtime, SDK design, workflow execution primitives, driver integration model, and log streaming. Some advanced capabilities, such as full DAG execution, secrets management, RBAC, namespacing, and observability improvements, are part of the roadmap.

For current progress, see the project roadmap:

- [Roadmap](https://conveyor.open.ug/docs/contributing/roadmap)
- [GitHub Milestones](https://github.com/open-ug/conveyor/milestones)

## Architecture

Conveyor CI separates orchestration from execution.

The control plane is responsible for managing workflow and job state. Drivers are responsible for actually running the workload.

| Component | Responsibility | Provided By |
| ----------------------------- | ------------------------------------------------------------------------------------ | ----------- |
| **Control Plane** | Job lifecycle management, state persistence, queuing, retries, log aggregation, APIs | Conveyor CI |
| **SDK** | Typed interface for interacting with the engine | Conveyor CI |
| **Drivers (Execution Logic)** | The code that actually runs workloads | **You** |

Conveyor does **not** ship Drivers, you define execution. This separation gives you, Infrastructure independence, Security model control, Hardware flexibility, Multi-environment support.
Conveyor does **not** ship drivers, you define execution. This separation gives you, Infrastructure independence, Security model control, Hardware flexibility, Multi-environment support.

## Core Capabilities

Expand All @@ -57,7 +98,7 @@ No UI. No opinionated runners. No vendor lock-in.

Just orchestration.

## Why This Design?
### Why This Design?

Most CI/CD platforms bundle UI, Execution environment, Orchestration logic, Storage, Scheduling, Opinionated infrastructure assumptions. Conveyor extracts the **orchestration layer** and leaves execution to you. This enables:

Expand All @@ -69,11 +110,20 @@ Most CI/CD platforms bundle UI, Execution environment, Orchestration logic, Stor

It’s the missing middle layer between Infrastructure and Developer-facing CI platforms.

## Example Use Case
## Installation

Conveyor CI is Linux-first and distributed as a lightweight Go binary.

You are building an Internal Developer Platform.
```bash
curl -fsSL conveyor.open.ug/install | sh
```

You want:
More installation options and configuration guides are available in the [official documentation](https://conveyor.open.ug/docs/installation).


### Example Use Case

You are building an Internal Developer Platform. You want:

* Teams to push code
* Pipelines to trigger
Expand All @@ -88,4 +138,10 @@ With Conveyor:

Clean separation. Clear ownership.

### Contributing

Please 🌟 star the project if you like it.

Contributions are welcome! Please read [contributing guide](https://conveyor.open.ug/docs/contributing/how-to-contribute) and follow the governance model to submit PRs, issues, or feature requests.

To install Conveyor CI, checkout the [Installation Page](/docs/installation)
Loading
Loading