Internals Reference

Core

kozmic.models

class kozmic.models.RepositoryBase

A base repository class to be used by HasRepositories mixin.

gh_id = Column(None, Integer(), table=None, nullable=False)

GitHub id

gh_name = Column(None, String(length=200), table=None, nullable=False)

GitHub name (i.e., kozmic)

gh_full_name = Column(None, String(length=200), table=None, nullable=False)

GitHub full name (i.e., aromanovich/kozmic)

gh_ssh_clone_url = Column(None, String(length=200), table=None, nullable=False)

SSH clone url

gh_https_clone_url = Column(None, String(length=200), table=None, nullable=False)

HTTPS clone url

is_public = Column(None, Boolean(), table=None, nullable=False)

Is the repository public?

classmethod from_gh_repo(gh_repo)

Constructs an instance of cls from gh_repo.

class kozmic.models.HasRepositories

Mixin that adds repositories relationship to the model. Repositories are stored in separate tables for each parent. Repository attribute contains model (inherited from RepositoryBase) mapped to the parent’s repositories table.

This pattern is well described in “Hand Coded Applications with SQLAlchemy” presentation by Mike Bayer.

class kozmic.models.User(**kwargs)

User account.

repositories

Set of user repositories.

organizations

Set of user organizations in which user has admin rights to at least one repository (see Organization).

gh_id

GitHub user id

gh_login

GitHub user login

gh_name

Human-readable GitHub name

gh_access_token

OAuth access token

gh_avatar_url

GitHub avatar URL

repos_last_synchronized_at

The last time when the user’s repositories and organizations were synced with GitHub

email

E-mail address

get_identity()

Returns user’s flask.ext.principal.Identity.

get_available_projects(annotate_with_latest_builds=False)

Returns list of Projects that user has access to. If annotate_with_latest_builds is specified, returns list of pairs (Projects, Build) where the second element is the latest project build or None if the project was never built.

gh

An authenticated GitHub session for this user.

Type:github3.github.GitHub

get_gh_org_repos()

Retrieves data from GitHub API and returns a pair of values:

1. set of github3.orgs.Organization in which the current user has at least one repository with admin rights;
2. dict mapping these organization’ ids to lists of github3.repo.Repository to which the current user has admin access.

get_gh_repos()

Retrieves data from GitHub API and returns a list of the user owned repositories.

Return type:list of github3.repo.Repository

sync_memberships_with_github()

Does the same as Project.sync_memberships_with_github(), but for the user. Returns True if there were not any GitHub errors; False otherwise.

class kozmic.models.Organization(**kwargs)

Stores a set of organization repositories that a user has admin access to.

Different Kozmic users, but members of the same GitHub organization, will have their own Organization entries with possibly different sets of repositories (because they are possibly members of different teams).

repositories

gh_id

GitHub organization id

gh_login

GitHub organization login

gh_name

Human-readable GitHub name

user

User whose admin rights is reflected by this organization

class kozmic.models.DeployKey(passphrase, key_size=2048)

An RSA deploy key pair.

gh_id

GitHub deploy key id

rsa_private_key

RSA private deploy key in PEM format encrypted with the app secret key

rsa_public_key

RSA public deploy key in OpenSSH format

ensure()

If the corresponding GitHub deploy key does not exist, creates it. Returns True if there weren’t GitHub API errors; False otherwise.

delete()

Deletes the public key from GitHub. Returns True if it has been successfully deleted (or was missing); False otherwise.

class kozmic.models.Project(**kwargs)

Project is a GitHub repository that is being watched by Kozmic CI.

gh_id

GitHub repo id

gh_name

GitHub repo name (i.e., kozmic)

gh_full_name

GitHub repo full name (i.e., aromanovich/kozmic)

gh_login

GitHub repo owner (user or organization) login

gh_ssh_clone_url

SSH repo clone url

gh_https_clone_url

HTTPS clone url

is_public

Is the project’s repository public?

deploy_key

Deploy key

members

Project members

owner

Project owner

gh

Project’s GitHub.

Type:github3.repos.Repository

delete()

Deletes the project and it’s corresponding GitHub entities such as hooks, deploy key, etc. Returns True if they all have been successfully deleted (or were missing); False otherwise.

get_latest_build(ref=None)

Return type:Build

sync_memberships_with_github()

Synchronizes project members with GitHub.

GitHub _repository members_ with admin and push rights become project managers, other _repository members_ become project members.

Returns True if there were not any GitHub errors; False otherwise.

class kozmic.models.Hook(**kwargs)

Reflects a GitHub hook.

gh_id

GitHub hook id

title

Title

install_script

Install script

build_script

Script to be run at hook call

docker_image

Name of a Docker image to run build script in (for example, “ubuntu” or “aromanovich/ubuntu-kozmic”). Specified docker image is pulled from index.docker.io before build

project

Project

ensure()

If the corresponding GitHub hook does not exist, creates it. If it exists, but has wrong configuration, re-configures it. Returns True if there weren’t GitHub API errors; False otherwise.

delete()

Deletes the project hook. Returns True if it’s corresponding GitHub hook is missing or has been successfully deleted; False otherwise.

class kozmic.models.TrackedFile(**kwargs)

Reflecs a tracked file.

path

Path within git repository

hook

Hook

class kozmic.models.Build(**kwargs)

Reflects a project commit that triggered a project hook.

number

Build number (within a project)

gh_commit_ref

Commit reference (branch on which the commit was pushed)

gh_commit_sha

Commit SHA

gh_commit_author

Commit author

gh_commit_message

Commit message

created_at

Created at

status

Build status, one of the following strings: ‘enqueued’, ‘success’, ‘pending’, ‘failure’, ‘error’

project

Project

calculate_number()

Computes and sets number.

started_at

Time the first job has started or None if there is no started jobs yet.

finished_at

Time the last job has finished or None if there is no finished jobs yet.

set_status(status, target_url='', description='')

Sets status and posts it on GitHub.

class kozmic.models.HookCall(**kwargs)

Reflects a fact that GitHub triggered a project hook.

created_at

Created at

gh_payload

JSON payload from a GitHub webhook request

hook

Hook

build

Build

class kozmic.models.Job(**kwargs)

A job that caused by a hook call.

started_at

Time the job has started or None

finished_at

Time the job has finished or None

return_code

Return code

stdout

Job log

task_uuid

uuid of a Celery task that is running a job

build

Build

hook_call

HookCall

get_cache_id()

Returns a string that can be used for tagging a Docker image built from the install script. A cache id changes whenever the base Docker image, the install script or any of the tracked files is changed.

Note

Requires that Docker is running and Docker base image (self.hook_call.hook.docker_image) is pulled.

started()

Sets started_at and updates build status. Must be called when the job is started.

finished(return_code)

Sets finished_at and updates build status. Must be called when the job is finished.

tailer_url

URL of a websocket that streams a job log in realtime.

permanent_url

A permanent URL of the job.

is_finished()

Is the job finished?

status

One of the following values: ‘enqueued’, ‘success’, ‘pending’, ‘failure’, ‘error’.

kozmic.perms

kozmic.perms.project_owner = <functools.partial object>

Project owner need

kozmic.perms.project_manager = <functools.partial object>

Project manager need

kozmic.perms.project_member = <functools.partial object>

Project member need

kozmic.perms.delete_project(id)

Returns a Permission to delete the project identified by id.

kozmic.perms.manage_project(id)

Returns a Permission to manage the project identified by id.

kozmic.perms.view_project(id)

Returns a Permission to view the project identified by id.

kozmic.builds.tasks

kozmic.builds.tasks.do_job(hook_call_id)

A Celery task that does a job specified by a hook call.

Creates a Job instance and executes a build script prescribed by a triggered Hook. Also sends job output to Job.task_uuid Redis pub-sub channel and updates build status.

Parameters:hook_call_id – int, HookCall identifier

kozmic.builds.tasks.restart_job(id)

A Celery task that restarts a job.

Parameters:id – int, Job identifier

class kozmic.builds.tasks.Publisher(redis_client, channel)

Parameters:

• redis_client – Redis client
• channel (str) – pub/sub channel name

class kozmic.builds.tasks.Tailer(log_path, publisher, container, kill_timeout=600)

A daemon thread that waits for additional lines to be appended to a specified log file. Once there is a new line, it does the following:

1. Translates ANSI sequences to HTML tags;
2. Sends the line to a Redis pub/sub channel;
3. Pushes it to Redis list of the same name.

If the log file does not change for kill_timeout seconds, specified Docker container will be killed and corresponding message will be appended to the log file.

Once the thread has finished, has_killed_container tells whether the :param:`container` has stopped by itself or been killed by a timeout.

Parameters:

• log_path (str) – path to the log file to watch
• publisher (Publisher) – publisher
• container (dictionary returned by docker.Client.create_container()) – container to kill
• kill_timeout (int) – number of seconds since the last log append after which kill the container

class kozmic.builds.tasks.Builder(docker, message_queue, docker_image, script, working_dir, clone_url, commit_sha, deploy_key=None)

A thread that starts a script in a container and waits for it to complete.

One of the following attributes is not None once the thread has finished:

return_code

Integer, a build script’s return code if everything went well.

exc_info

exc_info triple (type, value, traceback) if something went wrong.

Parameters:

• docker (docker.Client) – Docker client
• message_queue (Queue.Queue) – a queue to which put an identifier of the started Docker container. Identifier is a dictionary returned by docker.Client.create_container(). Builder will block until the message is acknowledged by calling Queue.Queue.task_done().
• deploy_key (2-tuple of strings) – a pair of strings (private key, passphrase)
• docker_image (str) – a name of Docker image to be used for build_script execution. The image has to be already pulled from the registry.
• working_dir (str) – path of the directory to be mounted in container’s /kozmic path
• clone_url (str) – SSH clone URL
• commit_sha (str) – SHA of the commit to be checked out

Packages Overview

kozmic

kozmic.__init__.create_app(config=None)

Returns a fully configured Flask application.

Parameters:config – a config object or it’s name. Will be passed directly to flask.config.Config.from_object(). If not specified, the value of KOZMIC_CONFIG environment variable will be used. If KOZMIC_CONFIG is not specified, 'kozmic.config.DefaultConfig' will be used.

kozmic.accounts

kozmic.accounts.bp

flask.Blueprint that gives users a means to manage their account settings.

kozmic.auth

kozmic.auth.bp

flask.Blueprint that implements an authentication through GitHub.

kozmic.builds

kozmic.builds.bp

flask.Blueprint that implements webhooks to be triggered by GitHub and serves status badges.

Note

Does not require authentication.

kozmic.projects

kozmic.projects.bp

flask.Blueprint that provides all the means for managing and viewing projects.

kozmic.repos

kozmic.repos.bp

flask.Blueprint that gives users the abilities to:

1. View list of GitHub repositories they have admin access to
2. Create kozmic.models.Project for any of them