Internals Reference¶
Core¶
kozmic.models¶
-
class
kozmic.models.
RepositoryBase
[source]¶ 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?
-
-
class
kozmic.models.
HasRepositories
[source]¶ Mixin that adds
repositories
relationship to the model. Repositories are stored in separate tables for each parent.Repository
attribute contains model (inherited fromRepositoryBase
) 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)[source]¶ 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_available_projects
(annotate_with_latest_builds=False)[source]¶ 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 orNone
if the project was never built.
-
get_gh_org_repos
()[source]¶ Retrieves data from GitHub API and returns a pair of values:
set
ofgithub3.orgs.Organization
in which the current user has at least one repository with admin rights;dict
mapping these organization’ ids to lists ofgithub3.repo.Repository
to which the current user has admin access.
-
get_gh_repos
()[source]¶ 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
()[source]¶ 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)[source]¶ 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
-
-
class
kozmic.models.
DeployKey
(passphrase, key_size=2048)[source]¶ 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
-
-
class
kozmic.models.
Project
(**kwargs)[source]¶ 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
-
-
class
kozmic.models.
Hook
(**kwargs)[source]¶ 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
-
-
class
kozmic.models.
TrackedFile
(**kwargs)[source]¶ Reflecs a tracked file.
-
path
¶ Path within git repository
-
hook
¶ Hook
-
-
class
kozmic.models.
Build
(**kwargs)[source]¶ 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
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
-
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.
-
-
class
kozmic.models.
HookCall
(**kwargs)[source]¶ 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)[source]¶ 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
-
get_cache_id
()[source]¶ 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
()[source]¶ Sets
started_at
and updatesbuild
status. Must be called when the job is started.
-
finished
(return_code)[source]¶ Sets
finished_at
and updatesbuild
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.
-
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)[source]¶ Returns a
Permission
to delete the project identified byid
.
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 triggeredHook
. Also sends job output toJob.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)[source]¶ Parameters: - redis_client – Redis client
- channel (str) – pub/sub channel name
-
class
kozmic.builds.tasks.
Tailer
(log_path, publisher, container, kill_timeout=600)[source]¶ 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:
- Translates ANSI sequences to HTML tags;
- Sends the line to a Redis pub/sub channel;
- 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:
-
class
kozmic.builds.tasks.
Builder
(docker, message_queue, docker_image, script, working_dir, clone_url, commit_sha, deploy_key=None)[source]¶ 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 bydocker.Client.create_container()
. Builder will block until the message is acknowledged by callingQueue.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)[source]¶ 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 ofKOZMIC_CONFIG
environment variable will be used. IfKOZMIC_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.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:- View list of GitHub repositories they have admin access to
- Create
kozmic.models.Project
for any of them