Code Change Reviews

Guide on recording and reporting Code Change Reviews using Ketryx

1. Introduction

1.1. Purpose

Code reviews play a crucial role in the software development lifecycle as they help identify and rectify defects, security vulnerabilities, and other issues in the software code.

This guide is dedicated to providing guidance on setting up code reviews in Ketryx. It aims to address common questions and offer insights into the process of establishing code reviews.

1.2. Tools

Tools used to develop and release a product with Ketryx Lifecycle Management are provided in MAN-01 Ketryx Lifecycle Management. The release process is described in detail in MAN-02 Software Release Process, while setting up code repositories is described in MAN-03 Supply Chain Management.

2. Supported platforms

Ketryx supports Code Change Review (CCR) data fetching for repositories hosted on GitHub and Bitbucket.

If you need support for other platforms like GitLab, Azure DevOps, etc., please contact our support.

3. Setup

Please see our SOUP documentation for more information about adding your repository to Ketryx: MAN-03 Supply Chain Management

3.1. GitHub

If you've added your GitHub repository, but still can't see the CCR Report, follow the below process to make sure you have added an authentication token for your repository in the project settings page.

1. Open the settings area of the project

2. Add the repository from which you want to pull the Code Change Reviews

3. Click Enable repository authentication,

   1. set username: name of the token (just for your own reference, can be anything),

   2. set password: the actual GitHub token

4. Click Save

There are several steps to generate a GitHub token (classic), which can be found here. To enable the CCR features, the token needs specific permissions mentioned below.

For Ketryx to fetch Pull Request data from GitHub, authentication needs to happen via a Personal Access Token. Access tokens can be generated at the user level and provide authorization for specific scopes.

This Personal Access Token will serve as the authentication method to fetch both Pull Request data and the Git repository for SOUP dependency analysis from GitHub.

To find out how to generate a classic or fine-grained Personal Access Token, please see our GitHub FAQ entry here.

The Personal Access Token needs certain permissions for the Code Change Review feature to work.

For the classic Personal Access Token, the following scopes are required:

1. repo

2. read:user

For the fine-grained Personal Access Token, the following permissions are required:

1. Contents

2. Metadata

3. Pull requests

3.2. Bitbucket access tokens

For Ketryx to fetch Pull Request data from Bitbucket, authentication needs to happen via a Repository Access Token. Access tokens can be defined at the repository, project, or organization level. Any of these work (just note that only the repository level is possible in the free version of Bitbucket). A guide on how to create such a token can be found here.

The same authentication method is used to fetch the Git repository (for SOUP dependency analysis) as well.

The repository access token needs to have at least the following permissions:

1. Repository: Read

2. Pull requests: Read

When entering the authentication credentials in Ketryx, set the following:

1. Username: x-token-auth (as a verbatim value, as documented here)
2. Password: (the access token)

4. Generating a Code Change Review report in Ketryx

Once set up, the Code Change Review report is available on a project's Code page. To go there, navigate to the project for which a report should be generated. In the Configuration section of the sidebar, press Code. In the upper right hand corner of the page is a download button that will generate the report and initiate a download. Optionally, choose a version for which you want to generate the report for.

Additionally, the Code Change Review report can be generated and approved for a release on a version's Documents page.