SKA CICD Services API
How to use
Please install all the requirements with your preferred python virtual environment with the following bash command:
virtualenv venv
source venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install -r requirements-dev.txt
Note: Depending on your environment you may need to update your ‘setuptools’ to install dependencies: ‘python3 -m pip install -U setuptools’.
Run lint with the following command:
make lint
This project uses tox environments. Run tests with the following command:
make test
or test only a single feature (set the FEATURE variable):
make test_feature FEATURE=jira
Note: Tests assume you have Python 3.8 available.
Clean with the following command:
make clean
GitLab API
The module ska_cicd_services_api.gitlab provides a class named GitLabApi which enables following:
Get authenticated user information
Get git diffs of a commit in a project
Add a comment to a merge request (MR)
Remove a comment from a merge request (MR)
Get MR information
Modify MR information
Get MR Approvals (Approver related settings)
Modify MR Approval settings
Get project level merge request approvals settings (Maintainer related settings)
Modify project level merge request approvals settings
Get all commits in an MR
Get Project settings information
Modify Project settings
Get Project members
Get list of merge request comments
Get a single comment in an MR
Modify a single comment in an MR
Search a string in project
Get file information in a branch
Create merge requests
Create branches
Delete branches
Trigger a Pipeline for Vulnerability Scanning
Approve MR
Unapprove MR
Download artifacts from Pipeline Job
It is also needed to define the OS variables in a PrivateRules.mak
file:
PRIVATE_TOKEN = yourauthenticationtoken
GITLAB_API_REQUESTER = yourrequesteruser
How to add a new API endpoint
Define the API method with a clear explanation in docstring following the rules:
Please include all the mandatory fields in the actual API documentation (GitLab’s API documentation) as mandatory arguments (no value assignment) and include all the optional arguments with defaul values.
Please use plurals in the method name if you are returning a list of results instead of a single item.
Please use appropriate verbs in method names:(the names are loosely mapped to the HTTP Methods in parantheses):
get(GET)
,create(POST)
,add(POST/PUT)
,modify(PUT)
,remove(DELETE)
. Please refrain with starting any other words.add
may be used for some requests that make more sense contextually such as adding approvals to an MR instead of creating approvals.If the method is returning a single item add
_info
postfix or plural form as explained above.Important: if the API endpoint is returning a single item, you should use
await self.gl.getitem(url)
method.Important: if the API endpoint is returning a list, you should use
self.gl.getiter(url)
method in order to ensure traversal of all results. Otherwise, it will only return first 20(default defined by GitLab API) results.
Write BDD tests for the API capability (relevant scenario and test fixtures)
Update the documentation in this README file
Jira API
The module ska_cicd_services_api.jira provides a class named SKAJira which enables following:
Get Project lists
Get a single issue
Create single/multiple issue(s)
Add a comment to a given issue
Delete a comment
Note that, the authenticated user must have necessary permissions for the above functionality to work correctly.
It is also needed to define the OS variables in a PrivateRules.mak
file:
JIRA_USERNAME = jirauser
JIRA_PASSWORD = strongpassword
JIRA_URL = https://jira.skatelescope.org
IGNORE_PROJECTS = IGP # list of project keys ignored
ReadtheDocs API
The module ska_cicd_services_api.readthedocs provides a class named ReadTheDocsApi which enables following:
Get subprojects of a project
Get details of a single subproject with given parent project name
Note that, the authenticated user must have necessary permissions for the above functionality to work correctly.
It is also needed to define the OS variables in a PrivateRules.mak
file:
RTD_TOKEN = authtokenforreadthedocs
Nexus API
The module ska_cicd_services_api.nexus provides a class named NexusApi which enables following:
Get components lists given a nexus repository
Get single component information given id
Remove a component from its associated repository given id
Upload a component to a nexus repository
Note that, the authenticated user must have necessary permissions for the above functionality to work correctly.
It is also needed to define the OS variables in a PrivateRules.mak
file:
NEXUS_API_USERNAME = jirauser
NEXUS_API_PASSWORD = strongpassword
NEXUS_URL = https://jira.skatelescope.org
Local Module Deployment and Testing
For local testing it might useful to install the modules with editable dependencies at the root (where setup.py
is located):
pip install -e .