Skip to content
Get packs

Guide · Open source

How to use OneDev: install, set up projects and CI/CD

Updated · written with AI from the project's own documentation and checked against our catalogue data

OneDev is an open-source, self-hosted web application that combines Git source code hosting, issue tracking with Kanban boards, CI/CD pipelines, built-in package registries and a project wiki. This guide explains what it covers, which platforms it supports and how its main features fit together. It is written for people who want to run their own development platform and need to decide whether OneDev is the right fit before installing it.

OneDevtheonedev/onedev · ★ 15.3k · MIT

Quick start

  1. 1Confirm your platform. Check that your server or workstation is Linux, Windows or macOS on Apple Silicon. Intel Macs and FreeBSD are not supported.
  2. 2Read the installation guide. Open the official installation guide linked from the README and follow its setup instructions for your environment.
  3. 3Start the server. Run OneDev using the method described in the installation guide and open the web interface in your browser.
  4. 4Create a project. Create a project and push an existing Git repository to it, or start with an empty one.
  5. 5Set up issues and boards. Create issue states and fields, then arrange a Kanban board and add transition rules where useful.
  6. 6Configure CI/CD. Create jobs in the GUI editor, choose an executor and attach jobs to your repository.

What OneDev includes

OneDev puts several development tools in one self-hosted application. The README highlights Git repository hosting, code review through pull requests, issue tracking, CI/CD, package registries and a wiki for project documentation.

You run it on your own servers rather than using a hosted service, so you keep control of your code and project data.

  • Git source code hosting
  • Issues with Kanban boards and custom workflows
  • CI/CD pipelines with a GUI job editor
  • Built-in package registries
  • Markdown wiki stored alongside your code

Check supported platforms before you install

The README says OneDev server and agent distributions support Linux and Windows on amd64/arm64, and macOS on Apple Silicon. Intel Macs, FreeBSD and other platforms are no longer supported.

Starting with OneDev 16.9.0, the Java Service Wrapper was replaced with OneDev Wrapper. The README points to the installation guide for setup instructions, so follow that guide for the exact steps on your system.

  • Supported: Linux and Windows (amd64/arm64), macOS on Apple Silicon
  • Not supported: Intel Macs, FreeBSD and other platforms

Manage code, reviews and issues

Code search and navigation work across any commit, with language-aware symbol search and regular-expression search. Pull requests can be protected with rules that require review or CI/CD checks when specific users change specific files on specific branches.

Issues can be moved manually on a Kanban board or automatically through rules tied to commits, tests, releases and deployments. Custom issue states and fields are supported, and time can be tracked on tasks and aggregated from subtasks.

  • Code discussions attached to selected code or diffs
  • Protection rules for files and branches
  • Manual or rule-based Kanban transitions
  • Time tracking and time sheets

Build CI/CD pipelines

CI/CD jobs can be created in a GUI editor, with templates for typical frameworks, typed parameters, matrix jobs, reusable logic and cache management. Jobs can run in containers, on bare metal or in isolated sandbox VMs, and can scale with Kubernetes or agents.

The README also lists debugging tools: a command to pause a job, a web terminal to inspect the job environment, and the ability to run a job locally against uncommitted changes.

  • Template-based and GUI job creation
  • Container, bare metal and sandbox VM executors
  • Kubernetes or agent-based scaling
  • Pause, web terminal and local-change debugging

Use packages, wiki and project structure

The built-in registry manages binary packages and can link them with CI/CD jobs. The wiki keeps Markdown pages next to your code, and you can edit them in the browser or with Git, review changes in pull requests, and browse any branch or release tag.

Projects can be arranged in a tree, with common settings defined in a parent project and inherited by child projects. Dashboards with gadgets can be shared with users or groups, or made public.

  • Package registry linked to CI/CD
  • Wiki editable in the browser or with Git
  • Parent-to-child project settings inheritance
  • Shareable dashboards

Plan for high availability and AI features

The README describes cluster setup for replicating projects across servers for high availability, or distributing projects for horizontal scalability. The README also describes built-in AI features that review pull requests, explain code, help with CI/CD specs and investigate build errors.

The AI features and browser-based workspaces for coding agents are described in the README's tutorials. Check those tutorials and the documentation for requirements before relying on them.

  • Cluster setup for high availability or scalability
  • Built-in AI for pull request review and build error investigation
  • Browser workspaces with dev containers or sandbox VMs

What people use it for

  • Hosting private Git repositories on your own servers
  • Running code review and CI/CD in one tool for a small development team
  • Handling customer support emails as issues without requiring customer accounts
  • Storing internal packages next to the source code that builds them
  • Keeping versioned project documentation in a wiki that follows branches and tags

Frequently asked questions

Is OneDev free?

OneDev is released under the MIT licence, according to the repository. The MIT licence generally permits use, modification and distribution, but read the licence file in the repository for the full terms.

What operating systems does OneDev support?

The README says OneDev server and agent distributions support Linux and Windows on amd64/arm64, and macOS on Apple Silicon. Intel Macs, FreeBSD and other platforms are no longer supported.

Do I need to install OneDev myself?

Yes. OneDev is self-hosted, so you run it on your own servers. The README points to an installation guide for setup instructions.

How does OneDev compare to GitLab or Gitea?

OneDev bundles Git hosting, issues, CI/CD, package registries and a wiki in one application, as do GitLab, Gitea and Forgejo to varying degrees. This guide does not benchmark them, so compare feature lists and platform support against your own needs.

Can I use OneDev with Jenkins?

OneDev includes its own CI/CD system, so you may not need Jenkins for pipelines. Whether it replaces Jenkins for your workflow depends on the jobs and integrations you need.

Is OneDev suitable for beginners?

Its feature set is large and it must be installed and maintained by you. It suits teams that want a full self-hosted platform more than people who only need a simple personal code backup.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OneDev suits teams that want Git hosting, issue tracking, CI/CD and packages on infrastructure they control, and that can maintain a self-hosted server. If you want zero server maintenance, need Intel Mac or FreeBSD support, or only need a simple personal code backup, pick a lighter or hosted option instead.

Install options & downloads