Provides tools for interacting with OneDev 13+ through Git repositories, enabling AI agents to run CI/CD jobs against local changes, checkout pull requests, manage build specifications, and stream job logs in real-time.
Requires NGINX configuration for proper real-time log streaming when OneDev is deployed behind a reverse proxy, specifically disabling HTTP buffering for streaming API endpoints.
TOD - TheOneDev CLI Tool
TOD (TheOneDev) is a powerful command-line tool for OneDev 13+ that streamlines your development workflow by enabling you to run CI/CD jobs against local changes, set up local working directory to work on pull requests, etc. It also offers a comprehensive Model Context Protocol (MCP) server with tools and prompts, enabling you to interact with OneDev 13+ through AI assistants in an intelligent and natural way.
Features
MCP (Model Context Protocol) server for AI tool integration
Run CI/CD jobs against local changes without committing/pushing
Run jobs against specific branches or tags
Checkout pull requests locally
Check and migrate build specifications to the latest version
Real-time log streaming to console from job execution
Configuration management via config files
Cross-platform support (Windows, macOS, Linux)
Installation
To install tod, just put tod binary into your PATH.
Download Pre-built Binaries
https://code.onedev.io/onedev/tod/~builds?query=%22Job%22+is+%22Release%22
Build Binary from Source
Requirements:
Go 1.22.1 or higher
Steps:
Clone the repository:
git clone https://code.onedev.io/onedev/tod.git cd todBuild the binary:
go build
Configuration
TOD uses a configuration file to store commonly used settings, eliminating the need to specify them repeatedly.
Config File Location
Create a config file at: $HOME/.todconfig
Config File Format
The configuration uses INI format:
Commands
mcp
- Start MCP Server
Start the Model Context Protocol server for AI tool integration.
Syntax:
Options:
--log-file <file>
- Specify log file path for debug logging
Example:
For detailed information about available MCP tools and their parameters, see
run-local
- Run Jobs Against Local Changes
Run CI/CD jobs against your uncommitted local changes without the commit/push/run/check loop.
Syntax:
Options:
--working-dir <dir>
- Specify working directory (defaults to current directory). Working directory is expected to be inside a git repository, with one of the remote pointing to a OneDev project--param <key=value>
or-p <key=value>
- Specify job parameters (can be used multiple times)
Examples:
How it works:
Stashes your local changes
Creates a temporary commit
Pushes to a temporal ref on the server
Runs the specified job
Streams logs back to your terminal
Cancels the job if you press Ctrl+C
run
- Run Jobs Against Branches or Tags
Run CI/CD jobs against specific branches or tags in the repository.
Syntax:
Options:
--working-dir <dir>
- Specify working directory (defaults to current directory). Working directory is expected to be inside a git repository, with one of the remote pointing to a OneDev project--branch <branch>
- Run against specific branch (mutually exclusive with --tag)--tag <tag>
- Run against specific tag (mutually exclusive with --branch)--param <key=value>
or-p <key=value>
- Specify job parameters (can be used multiple times)
Examples:
checkout
- Checkout Pull Requests
Checkout pull requests locally for testing and review.
Syntax:
Options:
--working-dir <dir>
- Specify working directory (defaults to current directory). Working directory is expected to be inside a git repository, with one of the remote pointing to a OneDev project
Example:
check-build-spec
- Check and Migrate Build Specifications
Check your .onedev-buildspec.yml
file for validity and migrate it to the latest version if needed.
Syntax:
Options:
--working-dir <dir>
- Directory containing build spec file (defaults to current directory). Working directory is expected to be inside a git repository, with one of the remote pointing to a OneDev project
Example:
Usage Examples
Complete Workflow Example
Set up configuration:
# Create ~/.todconfig echo "server-url=https://onedev.example.com" > ~/.todconfig echo "access-token=your-token-here" >> ~/.todconfigTest local changes:
# Run CI against your uncommitted changes cd /path/to/onedev-git-repository tod run-local ciRun against specific branch:
# Run ci job against the main branch cd /path/to/onedev-git-repository tod run --branch main ciCheckout a pull request:
# Checkout pull request #123 cd /path/to/onedev-git-repository tod checkout #123
Parameter Usage
Important Notes to Run Local Job
Nginx Configuration
If OneDev is running behind Nginx, configure it to disable HTTP buffering for real-time log streaming:
See OneDev Nginx setup documentation for details.
Security Considerations
If the job accesses job secrets. Make sure the authorization field is cleared to allow all jobs. Set authorization to allow all branches is not sufficient as local change will be pushed to a temporal ref not belonging to any branch
Performance Tips
Large repositories: Use appropriate clone depth in checkout steps instead of full history
External dependencies: Implement caching for downloads and intermediate files
Build optimization: Cache slow-to-generate intermediate files
Contributing
TOD is part of the OneDev ecosystem. For contributions, issues, and feature requests, visit the OneDev project.
License
See license.txt for license information.
This server cannot be installed
Interact with OneDev for CI/CD spec editing, pull request review, and issue workflow automation etc.