Extensions

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

There are app extensions and server extensions.

App extensions affect only the apps which app config they're declared in. One app can have many app extensions; moreover, it can have the same extension used many times. For example, you can use File Logs extension to write the error log and use the same extension to write the debug log to a different location.

Server extensions are invoked in the server config. These extensions change the way Sloth CI server works. For example, 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 extension is the Sloth CI API: all web API methods and CLI commands except for cli-start are implemented in an extension.

The same extension can work on both app and server levels.

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 recipient emails, and enter your SMTP credentials. Optionally, you can set the subject for each notification level.

Installation

$ pip install sloth-ci-ext-notifications

Usage

extensions:
    notifications:
        # Use the module sloth_ci_ext_notifications.
        module: 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

Devtools

Installation

$ pip install sloth-ci-ext-devtools

Usage

Enable the extension in the server config:

extensions:
    dev:
        # Use the module sloth_ci_ext_devtools.
        module: devtools

Call 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.

Logs

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-logs

Usage

extensions:
    logs:
        # Use the module sloth_ci_ext_logs.
        module: 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

Robots.txt

Shields.io

SSH Exec

Webhooks