Extensions

Extensions add new functionality to Sloth CI server and apps. Extensions change the way an app runs actions, add logging, send emails, new API methods and CLI commands, and much more.

One app config can have many extensions; moreover, it can have the same extension used many times. For example, you can use the File Logs extension to write the error log and use the same extension to write the debug log into a different location.

Server-level extensions are invoked in the server config. These extensions change the way Sloth CI server works. For example, the Robots.txt extension protects the server from bots; this doesn’t affect any particular app but affects the whole server.

Another example of a server-level extension is the Sloth CI API: all web API methods and CLI commands apart from start are implemented in an extension.

A single extension can work on both the app and server levels.

Here is the list of currently available extensions. If you want to create your own extension, refer to the developer guide.

See also

API and DB extensions are shipped with Sloth CI and are documented in the API docs.

Build Email Notifications

Send email notifications when builds complete or fail.

Executing actions of an app is called build. A build is considered completed if all its actions were completed. If some actions were completed and some failed, it’s a partially completed; if all actions fail, the build failed.

This extension sends you emails via SMTP when your builds complete (fully or partially) or fail; just pick the desired notification level, list the recepient emails, and enter your SMTP credentials. Optionally, you can set the subject for each notifcation level.

Warning

This extension uses SMTPHandler from logging.handlers. SMTPHandler doesn’t work with GMail because it creates an smtplib.SMTP object to connect to the host, whereas GMail requires smtplib.SMTP_SSL.

Outlook.com works fine.

Installation

$ pip install sloth-ci.ext.build_email_notifications

Usage

build_email_notifications.yml
extensions:
    notifications:
        # Use the module sloth_ci.ext.build_email_notifications.
        module: build_email_notifications

        # Emails to send the notifications to.
        emails:
            - foo@bar.com
            - admin@example.com

        # Log level (number or valid Python logging level name).
        # ERROR includes only build fails, WARNING adds partial completions,
        # INFO adds completion, and DEBUG adds trigger notifications.
        # Default is WARNING.
        level: INFO

        # The "from" address in the emails. Default is "build@sloth.ci."
        from: notify@example.com

        # The email subject on build trigger. You can use the {listen_point} placeholder.
        # Default is "{listen_point}: Build Triggered."
        subject_triggered: 'Triggered build on {listen_point}!'

        # The email subject on build completion.You can use the {listen_point} placeholder.
        # Default is "{listen_point}: Build Completed."
        subject_completed: 'Hooray! {listen_point} works!'

        # The email subject on build partial completion. You can use the {listen_point} placeholder.
        # Default is "{listen_point}: Build Partially Completed."
        subject_partially_completed: 'Better than nothing on {listen_point}'

        # The email subject on build fail. You can use the {listen_point} placeholder.
        # Default is "{listen_point}: Build Failed."
        subject_failed: 'Fail on {listen_point}'

        # SMTP settings.
        # SMTP mail host and (if not default) port.
        # Mandatory parameter.
        mailhost: 'smtp-mail.outlook.com:25'

        # SMTP login.
        login: foo@bar.baz

        # SMTP password.
        password: bar

        # If the SMTP server requires TLS, set this to true. Default is false.
        # If necessary, you can provide a keyfile name or a keyfile and a certificate file names.
        # This param is used only if the login and password params are supplied.
        secure: true
        # secure:
        #    -   keyfile
        #    -   cerfile
sloth_ci.ext.build_email_notifications.extend_sloth(cls, extension)[source]

Add an SMTP handler to the default logger when the app is created and remove it when the app stops.

Developer Tools

Utilities to help you develop extensions and validators for Sloth CI.

Installation

$ pip install sloth-ci.ext.devtools

Usage

Enable the extension in the server config:

devtools.yml
extensions:
    dev:
        # Use the module sloth_ci.ext.devtools.
        module: devtools

Call the sci dev with -e or -v to create an extensions or a validator template:

$ sci dev -e spam
Extension "spam" created.

$ sci dev -v eggs
Validator "eggs" created.
sloth_ci.ext.devtools.extend_cli(cls, extension)[source]

Add CLI commands to create extension and validator templates.

Docker Exec

Run actions inside a Docker image.

By default, Sloth CI apps run actions in a subprocess on the same machine they’re running on. This extension overrides this and makes the app execute each action as a container inside a given Docker image.

Installation

$ pip install sloth-ci.ext.docker_exec

Usage

docker_exec.yml
extensions:
    run_in_docker:
        # Use the module sloth_ci.ext.docker_exec.
        module: docker_exec

        # Image name. If missing, slug of the Sloth app listen point is used.
        # image: foo

        # Path to the Docker daemon to connect to. Can point to either a tcp URL or a unix socket. If missing, the client connects to /var/run/docker.sock.
        # base_url: tcp://555.55.55.55:5555 *.

        # Docker API version used on the server. If missing, the latest version is used.
        # version: 1.10

        # Path to the Dockerfile used to build an image if it doesn't exist. If missing, current directory is used.
        # path_to_dockerfile: docker/files

        # Memory limit in MB.
        # memory_limit: 10

        # CPU share in per cent.
        # cpu_share: 5
sloth_ci.ext.docker_exec.extend_sloth(cls, extension)[source]

Replace the default execute method with the Docker-based one.

File Logs

Add file logging to Sloth CI apps.

You can customize your logging in a number of ways: set the output dir and filename, set log level and format, toggle and configure log rotation.

Installation

$ pip install sloth-ci.ext.file_logs

Usage

file_logs.yml
extensions:
    logs:
        # Use the module sloth_ci.ext.file_logs.
        module: file_logs

        # Set the log path. Default is the current dir.
        path: debug_logs

        # Log filename. If not given, the app's listen point is used.
        filename: test_debug.log

        # Log level (number or valid Python logging level name).
        level: DEBUG

        # Log format (refer to the https://docs.python.org/3/library/logging.html#logrecord-attributes).
        # By default, this format is used: 
        # format: '%(asctime)s | %(name)30s | %(levelname)10s | %(message)s'

        # Make logs rotating. Default is false.
        # rotating: true

        # If rotating, maximum size of a log file in bytes.
        # max_bytes: 500

        # If rotating, maximum number or log files to keep.
        # backup_count: 10
sloth_ci.ext.file_logs.extend_sloth(cls, extension)[source]

Add a file handler to the default logger when the app is created and remove it when the app stops.

OpenVZ Exec

Run actions inside an OpenVZ container.

By default, Sloth CI apps run actions in a subprocess on the same machine they’re running on. This extension overrides this and makes the app execute actions inside a given OpenVZ container.

Installation

$ pip install sloth-ci.ext.openvz_exec

Usage

openvz_exec.yml
extensions:
    run_in_openvz:
        # Use the sloth_ci.ext.openvz_exec module.
        module: openvz_exec

        # Container name.
        container_name: foo

        # Container ID.
        # container_id: 123

If container_name is provided, container_id is ignored. If container_name is not provided, container_id is mandatory.

sloth_ci.ext.openvz_exec.extend_sloth(cls, extension)[source]

Replace the default execute method with the OpenVZ-based one.

Robots.txt

Robots.txt for the Sloth CI server.

Robots.txt is a file you put on your server to protect certain URLs from being accessed by crawler bots.

By default,tThis extension serves robots.txt on the server root, e.g. http://example.com:8080/robots.txt. However, you can specify your own file to serve and the URL to serve it on.

Installation

$ pip install sloth-ci.ext.robots_txt

Usage

sloth.yml
extensions:
    robots_txt:
        # Use the sloth_ci.ext.robots_txt module.
        module: robots_txt

        # Absolute path to the custom robots.txt file.
        # If not given, the bundled one is used (disallows everything to everyone).
        # file: ~/robots.txt

        # URL path to robots.txt.
        # By default the file is available in the root: *http://example.com:8080/robots.txt*.
        # path: /static/robots.txt
sloth_ci.ext.robots_txt.extend_bed(cls, extension)[source]

Mount robots.txt on the CherryPy tree during server configuration.

Shields.io

Status build badges for Sloth CI apps, powered by http://shields.io.

Installation

$ pip install sloth-ci.ext.shields_io

Usage

  1. Enable the extension in the server config:

    sloth.yml for Shields.io
    extensions:
        shields:
            # Use the module sloth_ci.ext.shields_io.
            module: shields_io
    
            # Badge label. You can use the ``{app}`` and ``{timestamp}`` placeholders for app name and build timestamp.
            # label: "My Sloth CI Status for {app}" # default is ``Sloth CI: {app}``
    
            # Badge status. You can use ``{status}``, ``{app}``, and ``{timestamp}`` placeholders build status, app name, and build timestamp
            # status: "{status}" # default is ``{status}, {timestamp}``
    
            # Badge style: ``plastic``, ``flat``, ``flat-square``, or ``social``
            # style: social # default is ``flat``
    
            # Badge format: svg, png, jpg, or gif
            # format: png # default is svg
    
            # Color map for build statuses
            # colors:
            #    INFO: green # default is ``brightgreen``
            #    WARNING: yellowgreen # default is ``yellow``
            #    ERROR: orange # default is ``red``
            ...
    

    All params are optional.

  2. Use the URL http://host:port/app?action=shield to get your badge.

    You can customize the badge on the fly by passing label, style, and format query params:

sloth_ci.ext.shields_io.extend_bed(cls, extension)[source]

Replace the default app listener with the one that returns a shield from http://shields.io.

SSH Exec

Run actions on remote machines over SSH.

By default, Sloth CI apps run actions in a subprocess on the same machine they’re running on. This extension overrides this and makes the app execute actions on remote machines over SSH.

You can authenticate with login and password or by providing key files.

Installation

$ pip install sloth-ci.ext.ssh_exec

Usage

ssh_exec.yml
extensions:
    run_over_ssh:
        # Use the sloth_ci.ext.ssh_exec module.
        module: ssh_exec

        # Hosts, comma-delimited. Optional port number can be provided after ':' (if not specified, 22 is used).
        hosts:
            - ssh.example.com
            - myserver.com:23

        # Username to use for authentication.
        username: admin

        # Password to use for authentication or to unlock a private key.
        # password: foobar

        # Additional private key files. If not specified, only the keys from the default location are loaded (i.e. ~/.ssh).
        # keys: 
        #   - ~/my_ssh_keys/key_rsa
        #   - somekey
sloth_ci.ext.ssh_exec.extend_sloth(cls, extension)[source]

Replace the default execute method with the SSH-based one.

Webhooks

Send POST requests on build events in Sloth CI apps.

Executing actions of an app is called build. A build is considered completed if all its actions were completed. If some actions were completed and some failed, it’s a partially completed; if all actions fail, the build failed.

This extension sends POST requests when your builds complete (fully or partially) or fail; just pick the desired notification level and the target URL.

Installation

$ pip install sloth-ci.ext.webhooks

Usage

webhooks.yml
extensions:
    webhooks:
        # Use the module sloth_ci.ext.webhooks.
        module: webhooks

        # Log level (number or valid Python logging level name).
        # ERROR includes only build fails, WARNING adds partial completions,
        # INFO adds completion, and DEBUG adds trigger notifications.
        # Default is WARNING.
        level: INFO

        # URL to send the requests to.
        url: http://example.com
class sloth_ci.ext.webhooks.POSTHandler(url)[source]

Log handler that sends records in POST requests to a particular URL.

Parameters:url – URL to send the requests to.
emit(record)[source]

Send a log record in a POST request to the specified URL.

Parameters:record – the record to send
sloth_ci.ext.webhooks.extend_sloth(cls, extension)[source]

Add a POST handler to the default logger when the app is created and remove it when the app stops.