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 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)[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 or None if the project was never built.
- get_gh_org_repos()[source]¶
Retrieves data from GitHub API and returns a pair of values:
- set of github3.orgs.Organization in which the current user has at least one repository with admin rights;
- dict mapping these organization’ ids to lists of github3.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
- 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 updates build status. Must be called when the job is started.
- finished(return_code)[source]¶
Sets finished_at and updates build status. Must be called when the job is finished.
kozmic.perms¶
- kozmic.perms.project_owner = <functools.partial object at 0x42ddd60>¶
Project owner need
- kozmic.perms.project_manager = <functools.partial object at 0x43ded60>¶
Project manager need
- kozmic.perms.project_member = <functools.partial object at 0x43dedb8>¶
Project member need
- kozmic.perms.delete_project(id)[source]¶
Returns a Permission to delete the project identified by id.
kozmic.builds.tasks¶
- kozmic.builds.tasks.do_job(hook_call_id)[source]¶
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)[source]¶
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 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)[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 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.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