<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Rusty-CI</title>
<meta name="robots" content="noindex" />
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li><a href="introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><a href="installation.html"><strong aria-hidden="true">2.</strong> Installation</a></li><li><a href="usage/usage.html"><strong aria-hidden="true">3.</strong> Usage</a></li><li><ol class="section"><li><a href="usage/help.html"><strong aria-hidden="true">3.1.</strong> Help Subcommand</a></li><li><a href="usage/setup.html"><strong aria-hidden="true">3.2.</strong> Setup Subcommand</a></li><li><a href="usage/install.html"><strong aria-hidden="true">3.3.</strong> Install Subcommand</a></li><li><a href="usage/build.html"><strong aria-hidden="true">3.4.</strong> Build Subcommand</a></li><li><a href="usage/start.html"><strong aria-hidden="true">3.5.</strong> Start Subcommand</a></li><li><a href="usage/stop.html"><strong aria-hidden="true">3.6.</strong> Stop Subcommand</a></li></ol></li><li><a href="yaml.html"><strong aria-hidden="true">4.</strong> Input YAML</a></li><li><a href="tldr.html"><strong aria-hidden="true">5.</strong> Too Long, Didn't Read</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Rusty-CI</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1><a class="header" href="#introduction" id="introduction">Introduction</a></h1>
<h2><a class="header" href="#what-is-rusty-ci" id="what-is-rusty-ci">What is Rusty-CI?</a></h2>
<p>Rusty-CI is just a user interface for <a href="https://buildbot.net">buildbot</a>. Instead of having to write the Python for your CI project to get the versatility you want, just fill out Rusty-CI's template YAML file and it'll do the rest for you.</p>
<h2><a class="header" href="#suggestions" id="suggestions">Suggestions</a></h2>
<p>I highly recommend running this in some sort of container.
All features of Rusty-CI are tested using fresh Ubuntu 18.04 linux containers.</p>
<h2><a class="header" href="#usage" id="usage">Usage</a></h2>
<p>Here is the template YAML file that Rusty-CI will output for you to fill out with your own data.</p>
<p>It explains itself for the most part, but I'll be covering it in more detail in a later chapter.</p>
<pre><code class="language-yaml"># The required of Rusty-CI to build this CI
requires: x.x.x
# This section holds data specific to the master of the workers
master:
# The title subsection of the master holds the title of your web gui
title: "Rusty-CI"
title-url: "https://github.com/adam-mcdaniel/rusty-ci"
# This is the ip of the web-gui
webserver-ip: localhost
# This is the port of the web-gui
webserver-port: 8010
# The address of your repository
repo: "https://github.com/adam-mcdaniel/rusty-ci"
# The number of seconds to wait before checking for updates on your repository
# Two minutes is a good poll interval
poll-interval: 120
# This section holds data specific to the handler that will look for
# pull requests / merge requests on your repository
merge-request-handler:
# This is basically the website you're using for version control
# Right now, github and gitlab are the only supported sites
# If you're using an unsupported version control system, no worries,
# rusty-ci just wont run on pull requests.
version-control-system: github
# The username of the owner of the repository
owner: adam-mcdaniel
# The name of the repository
repo-name: rusty-ci
# You dont want to run arbitrary code on your machine when anyone
# makes a pull request. Rusty-CI will not test anyone's pull request
# if their username is not in this list.
# Note that this has no effect on GitLab merge request building!
# Rusty-CI will only build merge requests from a branch
# thats already inside the repository.
whitelist:
- adam-mcdaniel
# This section holds each worker
# You can have as many workers as youd like, just be sure to fill out
# each of their fields out properly.
workers:
# The name of this worker is `test-worker`
test-worker:
# The ip of the master
master-ip: localhost
# The worker's files will be installed in this directory.
# This can also be an absolute path
working-dir: 'test-worker'
# This section holds each scheduler.
# Like the workers section, you may have as many schedulers as youd like.
schedulers:
# Create a scheduler named `ci-change`
# This scheduler will trigger the `rusty-ci-test` builder whenever it
# detects a change in a yaml file for any branch.
ci-change:
# This scheduler triggers the `rusty-ci-test` builder.
# You can put as many builders as youd like here, and the scheduler will start them all.
builders:
- rusty-ci-test
# This will make the current scheduler run if the "your-scheduler-name-here"
# has run successfully. You can only put one scheduler name in this section.
# depends: "your-scheduler-name-here"
# IF YOU USE THE `depends` SECTION, YOU SHOULD REMOVE OR COMMENT THE FOLLOWING SECTIONS
# Using the depends section will ignore the `branch`, `triggers`, and `password` sections
# This is a regular expression that matches a branch.
# If there is a change in a branch whos name matches this regex,
# it will be checked by the following triggers section.
# THIS WILL ONLY USE THE FIRST REGULAR EXPRESSION IN THIS SECTION TO MATCH THE BRANCH
branch: ".*"
# If a change has occurred in a branch that matches the regex in the branch section,
# Then the files that were changed are matched against the regular expressions in the
# triggers section. You can have any number of regular expressions in the triggers section.
# If any one of them matches the name of a file that was changed in a matched branch,
# then the builders in this scheduler's `builders` section are executed.
triggers:
- '.*\.yaml'
- '.*\.sh'
- ".*Makefile"
# The password a whitelisted user can comment on a merge / pull request
# to mark it for testing; that is if the pull request was made by a non-whitelisted
# user. If the pull request was made by a whitelisted user, it is automatically run.
password: "ok to test"
# These are the builders that are executed by the schedulers
# Each has its own specific task that is delegated to one or more workers
# When a builder is run, its script is run on the command line.
# You can have as many builders as youd like as well.
builders:
# The name of the builder is `rusty-ci-test`
rusty-ci-test:
# This is the shell script that the workers will run when this builder is executed
# You can have as many instructions as youd like
# Mind you, you cannot use the |, >, <, >>, <<, etc. operators. Sadly, buildbot
# passes each item separated by whitespace as another parameter to function.
script:
- echo Hello world!
- echo Im an instruction in a script!
# These are the workers to delegate this build job to
workers:
- test-worker
# The repo to refresh from before running
repo: "https://github.com/adam-mcdaniel/rusty-ci"
</code></pre>
<h1><a class="header" href="#installation" id="installation">Installation</a></h1>
<h3><a class="header" href="#install-python3" id="install-python3">Install Python3</a></h3>
<p>You're gonna need <a href="https://www.python.org/">python3</a> to use Rusty-CI.</p>
<p>To install on a *nix system, run the following commands.</p>
<pre><code class="language-bash">apt update -y && apt upgrade -y
apt install -y build-essential python3-dev python3-pip python3-venv
</code></pre>
<p>You will need to be able to use <code>python3 -m pip</code> and <code>python3 -m venv</code>.</p>
<h3><a class="header" href="#install-rust" id="install-rust">Install Rust</a></h3>
<p>To install Rusty-CI, you must install Rust.
You if you're on a Unix like platform, can do so by running this shell command.</p>
<pre><code class="language-bash">curl https://sh.rustup.rs -sSf | sh
</code></pre>
<p>If you're on Windows, go to the <a href="https://rust-lang.org">rust website</a>. You'll need to download <code>rust-init.exe</code> and follow its instructions.</p>
<h3><a class="header" href="#install-rusty-ci-from-cratesio-package-registry-recommended" id="install-rusty-ci-from-cratesio-package-registry-recommended">Install Rusty-CI from Crates.io Package Registry (recommended)</a></h3>
<p>Now that you have Rust, you should be able to install Rusty-CI by running the following command.</p>
<pre><code class="language-bash">cargo install -f rusty-ci
</code></pre>
<p>This will automatically add Rusty-CI to your path, so we should be all done!</p>
<h3><a class="header" href="#build-from-source-not-recommended" id="build-from-source-not-recommended">Build from source (not recommended)</a></h3>
<p>If you don't want to install Rusty-CI from the package registry, you can always build Rusty-CI from source. Here's how you would do so.</p>
<pre><code class="language-bash">git clone https://github.com/adam-mcdaniel/rusty-ci
cd rusty-ci
# Cargo will output the executable to ./target/release/rusty-ci
cargo install -f --path .
</code></pre>
<p>This will automatically add Rusty-CI to your path, so we should be all done!</p>
<h3><a class="header" href="#problems-installing" id="problems-installing">Problems Installing?</a></h3>
<p>If you run into some problems installing Rusty-CI, or if Rust can't find <code>cc</code>, you need to upgrade some of the packages on your system.</p>
<p>Here's the commands I run to solve these errors.</p>
<pre><code class="language-bash">apt update -y && apt upgrade -y
sudo apt install build-essential
</code></pre>
<p>After running these commands, try running <code>cargo install rusty-ci</code> again.</p>
<h3><a class="header" href="#cant-find-cargo-or-rusty-ci" id="cant-find-cargo-or-rusty-ci">Can't find Cargo or Rusty-CI?</a></h3>
<p>Try running the following to add Cargo and your installed crates to your environment's path.</p>
<pre><code class="language-bash">source $HOME/.cargo/env # Add `cargo` to your path
</code></pre>
<h3><a class="header" href="#still-having-problems" id="still-having-problems">Still having problems?</a></h3>
<p>If you're still having some serious problems, <a href="https://github.com/adam-mcdaniel/rusty-ci/issues">post an issue</a> on the repository.</p>
<h1><a class="header" href="#usage-1" id="usage-1">Usage</a></h1>
<p>This chapter covers</p>
<ul>
<li>The features and usage of the <code>rusty-ci</code> executable</li>
<li>How to properly use the input YAML files for <code>rusty-ci</code></li>
</ul>
<h1><a class="header" href="#help-subcommand" id="help-subcommand">Help Subcommand</a></h1>
<p>Rusty-CI has several subcommands, the first of which is the <code>help</code> subcommand.
To run the help subcommand, run <code>rusty-ci help</code> or alternatively <code>rusty-ci</code>.
If you dont provide any arguments to <code>rusty-ci</code>, it will print the help message by default.</p>
<pre><code>rusty_ci x.x.x
Adam McDaniel <adam.mcdaniel17@gmail.com>
A continuous integration tool written in Rust
USAGE:
rusty-ci [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
build Build rusty-ci from YAML file(s)
help Prints this message or the help of the given subcommand(s)
install Install buildbot
rebuild Build and restart rusty-ci from input YAML file(s)
setup Output a template YAML files for you to change to customize
start Launch rusty-ci from an input YAML file
stop Stop rusty-ci
To start a project, run the `setup` subcommand.
Be sure to follow the instructions after each subcommand very carefully!
</code></pre>
<p>This tells you more about the program, but it doesn't go into any depth.
Let me explain each subcommand individually.</p>
<h1><a class="header" href="#setup-subcommand" id="setup-subcommand">Setup Subcommand</a></h1>
<p>The setup command is very simple. All it does is write template YAML files for building your CI and controlling email notifications to any paths you'd like.</p>
<pre><code>$ ./rusty-ci setup template.yaml mail.yaml
==[INFO]===> Writing template master yaml file to template.yaml...
==[INFO]===> Writing template mail yaml file to mail.yaml...
==[INFO]===> All done!
==[INFO]===> Next, run the `install` subcommand command using either the `bash` or `make` flag
</code></pre>
<pre><code>$ more template.yaml
# The required of Rusty-CI to build this CI
requires: x.x.x
# This section holds data specific to the master of the workers
master:
# The title subsection of the master holds the title of your web gui
title: "Rusty-CI"
title-url: "https://github.com/adam-mcdaniel/rusty-ci"
# This is the ip of the web-gui
webserver-ip: localhost
# This is the port of the web-gui
webserver-port: 8010
# The address of your repository
repo: "https://github.com/adam-mcdaniel/rusty-ci"
# The number of seconds to wait before checking for updates on your repository
# Two minutes is a good poll interval
poll-interval: 120
# This section holds data specific to the handler that will look for
# pull requests / merge requests on your repository
merge-request-handler:
# This is basically the website you're using for version control
...
</code></pre>
<pre><code>$ more mail.yaml
# Rusty-CI will automatically email "interested users" about
# all tests that run. The list of "interested users" is the
# list of people who have a commit in the branch or pull request.
# The extra recipients to email
extra-recipients:
# Emails under the failure section will be emailed
# info about every failed build
failure:
- failure@gmail.com
# Emails under the success section will be emailed
# info about every successful build
success:
- success@gmail.com
# Emails under the all section will be emailed
# info about every build
all:
- all_tests@gmail.com
# The "from" email address used to send email updates to recipients
from-address: your-email-here@gmail.com
# The suffix to add to the interested users' usernames
# to get an email we can send updates to.
lookup: gmail.com
# The smtp relay hostname (self explanatory)
# gmail's smtp relay hostname is `smtp.gmail.com`
smtp-relay-host: smtp.gmail.com
# The smtp relay port (self explanatory)
# 587 is the smtp port that `smtp.gmail.com` uses
smtp-port: 587
# The password used to login to the "from" email address account
smtp-password: "p@$$w0rd"
</code></pre>
<p>When the setup command is finished, run the <code>install</code> subcommand.</p>
<h1><a class="header" href="#install-subcommand" id="install-subcommand">Install Subcommand</a></h1>
<p>The <code>install</code> subcommand is responsible for installing Rusty-CI's dependencies. When you run the install subcommand, it will output a bash script that uses your existing <a href="https://www.python.org/">python3</a> installation to install <a href="https://buildbot.net/">buildbot</a> and its dependencies.</p>
<p>You can also choose to output a makefile instead of a bash script, but it's not really necessary.</p>
<h2><a class="header" href="#usage-2" id="usage-2">Usage</a></h2>
<p>To output a Makefile for installation, run one of the following commands.</p>
<pre><code class="language-bash"># Output an install makefile
rusty-ci install --make
# Identical
rusty-ci install -m
# Run the makefile to install
make
</code></pre>
<p>To output a bash script for installation, run one of the following commands.</p>
<pre><code class="language-bash"># Output an install shell script
rusty-ci install
# Identical
rusty-ci install --bash
# Make the shell script executable
chmod +x ./install.sh
# Run the install script
./install.sh
</code></pre>
<p>If you do decide to either the bash or make buildsystems, be sure to read <code>rusty-ci</code>'s output and follow any instructions given.</p>
<pre><code>$ rusty-ci install
==[INFO]===> Installing dependencies for rusty-ci...
Do you already have python3-dev, python3-pip, and python3-venv installed? (y/n) y
==[INFO]===> Writing install file to `./install.sh`
==[INFO]===> Successfully wrote install file
==[WARN]===> To install dependencies run `install.sh`
==[WARN]===> Before building from a YAML file, be sure to run `. venv/bin/activate`
==[INFO]===> Next, write your VCS's api token to 'auth.token', and then run the `build` subcommand
Successfully finished install
</code></pre>
<p>Now, get an access token from your version control system, and write it to a file named <code>auth.token</code>. Next, run the move on to the <code>build</code> subcommand.</p>
<h1><a class="header" href="#build-subcommand" id="build-subcommand">Build Subcommand</a></h1>
<p>The <code>build</code> subcommand is responsible for constructing the buildbot master, the buildbot workers, and their respective configuration files from a YAML file.</p>
<pre><code>rusty-ci-build x.x.x
Adam McDaniel <adam.mcdaniel17@gmail.com>
Build rusty-ci from YAML file(s)
USAGE:
rusty-ci build [FLAGS] [OPTIONS] <MASTER_YAML>
FLAGS:
-h, --help Prints help information
-q, --quiet Don't ask user anything
-V, --version Prints version information
OPTIONS:
-m, --mail <MAIL_YAML> The path to the YAML file dedicated to SMTP authentication info for sending email
notifications
ARGS:
<MASTER_YAML> The path to the master YAML file
</code></pre>
<h2><a class="header" href="#usage-3" id="usage-3">Usage</a></h2>
<!-- Before you build your YAML file, you need to get an API or authentication token from your respective Version Control System, and write it to `auth.token`. This is so the output buildbot project has access to push commit statuses to your repository, and other things like that. -->
<p>First, confirm that you're inside your python virtual environment.</p>
<pre><code class="language-bash">. venv/bin/activate
</code></pre>
<p>To build from a YAML file, simply run this command.</p>
<pre><code class="language-bash">rusty-ci build template.yaml
</code></pre>
<p>If you want to build your CI with support for email notifications, run it like so.</p>
<pre><code class="language-bash">rusty-ci build template.yaml --mail mail.yaml
# is identical to the following
rusty-ci build template.yaml -m mail.yaml
</code></pre>
<p>Now, run the start subcommand.</p>
<h1><a class="header" href="#start-subcommand" id="start-subcommand">Start Subcommand</a></h1>
<h2><a class="header" href="#usage-4" id="usage-4">Usage</a></h2>
<p>After running all the other rusty-ci subcommands, run</p>
<pre><code class="language-bash">rusty-ci start template.yaml
</code></pre>
<p>This will kill the master and workers that were previously running, and start new instances of them.</p>
<p>Now, to view your web gui, go to <a href="http://localhost:8010">http://localhost:8010</a>.</p>
<p>If you want to RESTART your CI without killing it, use the following subcommand instead.</p>
<pre><code class="language-bash">rusty-ci rebuild template.yaml mail.yaml
</code></pre>
<p>This will not start your CI if it hasn't already been started!</p>
<h2><a class="header" href="#not-working" id="not-working">Not working?</a></h2>
<p>Confirm you're in your python virtual environment!</p>
<p>If your web gui isn't loading, buildbot probably failed to start the master, or you put the wrong IP in the master section of your YAML file.</p>
<p>You probably just forgot to change the path to one of your worker's working directories, though.</p>
<p>To see the log for the master, run <code>tail -f master/twistd.log</code>.</p>
<p>If you see an exception, then the master ran into an error. This error will most likely be self explanatory and easy to debug, but in the case that it isn't, go to the <a href="https://buildbot.net">buildbot website</a>.</p>
<h1><a class="header" href="#stop-subcommand" id="stop-subcommand">Stop Subcommand</a></h1>
<h2><a class="header" href="#usage-5" id="usage-5">Usage</a></h2>
<p>First, confirm you're in your python virtual environment.</p>
<p>If you want to kill your CI and all of its processes, run the following.</p>
<pre><code class="language-bash">rusty-ci stop
</code></pre>
<p>This will kill Rusty-CI and all other python(3) processes!</p>
<h1><a class="header" href="#input-yaml" id="input-yaml">Input YAML</a></h1>
<p>The input YAML file is pretty simple, but here's an explanation of each section individually.</p>
<h2><a class="header" href="#the-requires-section" id="the-requires-section">The requires section</a></h2>
<p>The requires section declares the minimum required Rusty-CI version to build this CI.</p>
<pre><code class="language-yaml">requires: x.x.x
</code></pre>
<h2><a class="header" href="#the-master-section" id="the-master-section">The master section</a></h2>
<p>The master section contains the data that controls the master, the bot that controls the workers.</p>
<pre><code class="language-yaml"># This section holds data specific to the master of the workers
master:
# The title subsection of the master holds the title of your web gui
title: "Rusty-CI"
title-url: "https://github.com/adam-mcdaniel/rusty-ci"
# This is the ip of the web-gui
webserver-ip: localhost
# This is the port of the web-gui
webserver-port: 8010
# The address of your repository
repo: "https://github.com/adam-mcdaniel/rusty-ci"
# The number of seconds to wait before checking for updates on your repository
# Two minutes is a good poll interval
poll-interval: 120
</code></pre>
<h2><a class="header" href="#the-merge-request-handler-section" id="the-merge-request-handler-section">The merge-request-handler section</a></h2>
<p>The merge-request-handler section holds information that determines how <code>buildbot</code> will handle merge and pull requests on your repository.</p>
<p>Right now, this is only supported for <code>github.com</code>.</p>
<pre><code class="language-yaml"># This section holds data specific to the handler that will look for
# pull requests / merge requests on your repository
merge-request-handler:
# This is basically the website you're using for version control
# Right now, github and gitlab are the only supported sites
# If you're using an unsupported version control system, no worries,
# rusty-ci just wont run on pull requests.
version-control-system: github
# The username of the owner of the repository
owner: adam-mcdaniel
# The name of the repository
repo-name: rusty-ci
# You dont want to run arbitrary code on your machine when anyone
# makes a pull request. Rusty-CI will not test anyone's pull request
# if their username is not in this list.
# Note that this has no effect on GitLab merge request building!
# Rusty-CI will only build merge requests from a branch
# thats already inside the repository.
whitelist:
- adam-mcdaniel
</code></pre>
<h2><a class="header" href="#the-workers-section" id="the-workers-section">The workers section</a></h2>
<p>The workers section lists each worker and the information required to construct them and connect them to the master bot.</p>
<pre><code class="language-yaml"># This section holds each worker
# You can have as many workers as youd like, just be sure to fill out
# each of their fields out properly.
workers:
# The name of this worker is `test-worker`
test-worker:
# The ip of the master
master-ip: localhost
# The worker's files will be installed in this directory.
# This can also be an absolute path
working-dir: 'test-worker'
</code></pre>
<h1><a class="header" href="#the-schedulers-section" id="the-schedulers-section">The schedulers section</a></h1>
<p>This section lists each scheduler. Each scheduler has a regular expression that matches a branch to track, and a list of regular expressions that match file changes. A scheduler can also depend on another scheduler using the <code>depends</code> section INSTEAD of the <code>triggers</code>, <code>branch</code>, and <code>password</code> sections.</p>
<p>Read the comments in the template YAML for more information.</p>
<pre><code class="language-yaml"># This section holds each scheduler.
# Like the workers section, you may have as many schedulers as youd like.
schedulers:
# Create a scheduler named `ci-change`
# This scheduler will trigger the `rusty-ci-test` builder whenever it
# detects a change in a yaml file for any branch.
ci-change:
# This scheduler triggers the `rusty-ci-test` builder.
# You can put as many builders as youd like here, and the scheduler will start them all.
builders:
- rusty-ci-test
# This will make the current scheduler run if the "your-scheduler-name-here"
# has run successfully. You can only put one scheduler name in this section.
# depends: "your-scheduler-name-here"
# IF YOU USE THE `depends` SECTION, YOU SHOULD REMOVE OR COMMENT THE FOLLOWING SECTIONS
# Using the depends section will ignore the `branch`, `triggers`, and `password` sections
# This is a regular expression that matches a branch.
# If there is a change in a branch whos name matches this regex,
# it will be checked by the following triggers section.
# THIS WILL ONLY USE THE FIRST REGULAR EXPRESSION IN THIS SECTION TO MATCH THE BRANCH
branch: ".*"
# If a change has occurred in a branch that matches the regex in the branch section,
# Then the files that were changed are matched against the regular expressions in the
# triggers section. You can have any number of regular expressions in the triggers section.
# If any one of them matches the name of a file that was changed in a matched branch,
# then the builders in this scheduler's `builders` section are executed.
triggers:
- '.*\.yaml'
- '.*\.sh'
- ".*Makefile"
# The password a whitelisted user can comment on a merge / pull request
# to mark it for testing; that is if the pull request was made by a non-whitelisted
# user. If the pull request was made by a whitelisted user, it is automatically run.
password: "ok to test"
</code></pre>
<h2><a class="header" href="#the-builders-section" id="the-builders-section">The builders section</a></h2>
<p>The builders describe the tasks given to workers.</p>
<pre><code class="language-yaml"># These are the builders that are executed by the schedulers
# Each has its own specific task that is delegated to one or more workers
# When a builder is run, its script is run on the command line.
# You can have as many builders as youd like as well.
builders:
# The name of the builder is `rusty-ci-test`
rusty-ci-test:
# This is the shell script that the workers will run when this builder is executed
# You can have as many instructions as youd like
# Mind you, you cannot use the |, >, <, >>, <<, etc. operators. Sadly, buildbot
# passes each item separated by whitespace as another parameter to function.
script:
- echo Hello world!
- echo Im an instruction in a script!
# These are the workers to delegate this build job to
workers:
- test-worker
# The repo to refresh from before running
repo: "https://github.com/adam-mcdaniel/rusty-ci"
</code></pre>
<h1><a class="header" href="#tldr" id="tldr">TL;DR</a></h1>
<p>If you were too bored to read the whole thing, just paste this stuff into your terminal (I'm assuming you're using a Debian based OS).</p>
<pre><code class="language-bash"># Update && Upgrade
apt update -y && apt upgrade -y
apt install -y build-essential python3-dev python3-pip python3-venv
# Install rust
curl https://sh.rustup.rs -sSf | sh # Run the rust installer
source $HOME/.cargo/env # Add `cargo` to your path
cargo install -f rusty-ci # Install the latest rusty-ci release
# Write template yaml files
rusty-ci setup template.yaml mail.yaml
# Uncomment to modify your CI's settings to fit your project
# nano template.yaml # Controls how your CI tests your code
# nano mail.yaml # Defines email update / notification settings
# Install rusty-ci dependencies
rusty-ci install -q # Build install.sh
chmod +x ./install.sh # Make install.sh executable
./install.sh # Install!
# Enter venv
. venv/bin/activate # Enter the venv created by rusty-ci
# to avoid poisoning your environment
# Add an authentication token from your VCS (github)
echo "YOUR AUTH TOKEN HERE" > auth.token
# Construct your ci bot
rusty-ci build -q template.yaml --mail mail.yaml
# Spin up the workers!
rusty-ci start template.yaml -q
# All done!
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<!-- Livereload script (if served using the cli tool) -->
<script type="text/javascript">
var socket = new WebSocket("ws://localhost:3001");
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload(true); // force reload from server (not from cache)
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript">
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</body>
</html>
