MAN-09 Git-Based Configuration Items

Manual for incorporating Git-based Configuration Items into Ketryx Lifecycle Management

1. Introduction

Git-based configuration items allow users to maintain configuration items in Git repositories, i.e., in source code, rather than in or in parallel with a task/issue management tool (e.g., Jira). This way, users can maintain configuration items in the same place where they maintain the source code. By default, this feature works on an opt-in basis.

1.1. Purpose

The purpose of this manual is to instruct users on how to opt into Git-based configuration items feature and incorporate configuration items, whose content is managed in a Git repository.

1.2. Scope

This manual describes the ways of maintaining configuration items in Git repositories so that Ketryx can easily access them and incorporate them into the lifecycle management process. Furthermore, it instructs users on how to define relevant files locations, within a Git repository, for configuration items.

2. Opt-in via project settings

You can opt into Git-based configuration items by defining glob patterns during the project creation or configuration process. These glob patterns define the locations of configuration items within a Git repository and Ketryx will scan the repository for files that match these patterns. For example:

src/requirements/**/*.md
features/**/*.feature
!src/**/README.md

Ketryx will scan the repository for:

• All files with the .md extension in the src/requirements/ directory and all its subdirectories

• All files with the .feature extension in the features/ directory and all its subdirectories

• Omit all README.md files in the src/ directory and all its subdirectories

You can add multiple patterns per repository by defining each pattern in a new line.

Define glob pattern note

2.1. Choosing a specific parser

Ketryx supports associating metadata with a glob pattern. This way, you can define the name of the parser that Ketryx should use to parse the content of the files that match the glob pattern. The metadata is defined by prepending the glob pattern with PARSER_NAME:. PARSER_NAME is a built-in parser that Ketryx uses to parse the content of the files. The following parsers are supported:

• tests - for parsing source code test files. Learn more about the tests parser in the section 3.3.

tests:src/tests/**/*.java
tests:src/tests/**/*.kt
tests:src/tests/**/*.ktm
tests:src/tests/**/*.kts
tests:src/tests/**/*.swift

More parsers can be configured on demand.

2.2. New project setup

1. Please follow steps 1, 2, and 3 of the general project setup for initial instructions.
2. Optionally, you may need to enable repository authentication if the repository in question is a private repository. For more specific information on how to do this, see the specific integration guides for Bitbucket, GitHub, and GitLab.
3. Activate the Enable Git based Items checkbox and input the desired glob patterns, thus instructing Ketryx where to look for configuration items within the Git repository.
4. Optionally, you can connect a Jira project as well. For more specific information on how to do this, please consult the Jira guide.
5. To finalize the creation of the project, press the Create project button. The configuration items from the repository, matching glob patterns defined in step 2 will be automatically scanned and shown.

2.3. Update Project

1. Log into Ketryx Platform at app.ketryx.com by using your connected Google or GitHub account, or using your email addresses.
2. Navigate to the desired project and its Settings.

   • If you want to opt into Git-based configuration items for a repository that is already connected to Ketryx, continue with step 5.

   • If you want to opt into Git-based configuration items for a repository that is not yet connected to Ketryx, continue with step 3.

3. Press Add repository or Add another repository and input an BitBucket/GitHub/GitLab repository URL.

   • Please look at step 3 on the following link for optional instructions on how to connect a repository.
4. Optionally, you may need to enable repository authentication (if the repository in question is a private repository). For more specific information on how to do this for Bitbucket, GitHub, and GitLab, please see their respective FAQ entries by clicking on the links.
5. Activate Enable Git based Items and input desired glob patterns, thus instructing Ketryx where to look for configuration items within the Git repository.
6. Press the Save changes button. The configuration items from the repository, that match glob patterns defined in step 5, will be automatically scanned and shown.

3. Defining configuration items (supported file formats and content parsing)

Currently, Ketryx supports managing configuration items in:

• Markdown files (support for all item types)

• Cucumber files using Gherkin syntax (support for items of type Test Case)

• Java files (currently it supports items of type Test Case)

• Kotlin files (currently it supports items of type Test Case)

• Swift files (currently it supports items of type Test Case)

Based on the file type, you can define various fields in the content of the file that will be used to define the configuration item. Please have a look at the Item schema section of each item type to see which fields are available for defining the configuration item. Respective item types and their schemas are defined in the following work instructions:

• Requirement schema
• Software Item Spec schema
• Test Case schema
• Test Execution schema
• Risk schema

Git-based item versioning is based on the versioning of the repository. Thus, defining fields like Introduced in version or Obsolete in version has no effect. Learn more about versioning in the section 8.

Depending on the file type, the configuration item is defined in different ways. The following sections describe how to define configuration items and their fields in each of the supported file types.

itemId is a common field that can be used to uniquely identify a configuration item. If itemId is not explicitly specified, Ketryx will use the file path within the Git repository as a fallback. Learn more about uniquely identifying a configuration item in the section 4.

3.1. Markdown files - All types of configuration items

Each markdown file is considered to be a single configuration item and can be of any type that is specified in the configuration item types section.

3.1.1. Fields in the front matter

In the front matter of a Markdown file, you can define the following fields:

• itemId - a unique identifier of the configuration item

• itemType - the type of the configuration item

• itemTitle - the title of the configuration item that is used instead of the first heading of the main content

• All traceability fields that are used to define the relationship between configuration items

• Any other non rich-text field that is defined in the Item schema of the configuration item type

• Extra fields that you might have configured to be tracked under advanced settings (Ketryx treats these fields in a case-insensitive manner)

To define traceability to other configuration items, you can include any field that is defined in the traceability to other configuration items section in the front matter of the Markdown file.

itemId, itemType, itemTitle and traceability fields must be defined using the camelCase notation. Any other field that is defined in the Item schema of the configuration item type must be defined using the "natural language" notation as it is defined in the Item schema (e.g. Requirement type, Context, Test result)

---
itemId: some-unique-string-1234
itemType: Software Item Spec
itemFulfills: KP-42
itemImplements: KP-43, KP-44
Requirement type: Use case
Test result: Pass
My extra field: Simple text content
Context: Clinical
---

3.1.2. Fields in the main content

In the body of a Markdown file you can define all rich text fields that are defined in the Item schema. Here is how you can define the content of the configuration item so that Ketryx can parse it properly:

• The first heading of the main content is considered to be the title of the configuration item (unless there is an itemTitle defined in the front matter)

• The rest of the content Ketryx will parse based on the set of rules that are defined in the next section below

Rules for maintaining item fields in the main content:

• Ketryx looks for a special section called Item fields in the main content

• Inside the Item fields, Ketryx looks for headings that match the rich text field names defined in the Item schema of the configuration item type (e.g. Description, Inputs, Outputs, Steps, ...), or Extra fields that have defined in the advanced settings (Ketryx treats these fields in a case-insensitive manner)

  • These headings must be on a lower level than the Item fields heading

  • The content under the heading is considered to be the value of the field

• If there is no special heading for the Description, then the description is set to the whole content until the Item fields section (or until the end of the file if there is no such section)

# Add dose suggestion
This is part of the description, unless there's an explicit ### Description under ## Item fields.
## Description
still part of the description
## Item fields
### Inputs
Inputs content
### Outputs
Outputs content
## Another section
Another section that will be ignored

Given the example above, Ketryx will extract the following fields:

• Title: Add dose suggestion

• Description:

  This is part of the description, unless there's an explicit ### Description under ## Item fields.
  ## Description
  still part of the description

• Inputs: Inputs content

• Outputs: Outputs content

However, if the Description heading is defined under the Item fields section, the description will be set to the content under the Description heading.

# Add dose suggestion
This is not part of the description and will be ignored.
## Item fields
### Description
This is the description of the item
### Inputs
Inputs content
### Outputs
Outputs content
## Another section
Another section that will be ignored

Given the example above, Ketryx will extract the following fields:

• Title: Add dose suggestion

• Description: This is the description of the item

• Inputs: Inputs content

• Outputs: Outputs content

Finally, if the Item fields section is not defined, Ketryx will consider the whole content of the file as the description of the configuration item.

# Add dose suggestion
Everything below the title is considered to be the description of the item.
### Inputs
Inputs content
### Outputs
Outputs content
## Another section
Another section content

Given the example above, Ketryx will extract the following fields:

• Title: Add dose suggestion

• Description:

  Everything below the title is considered to be the description of the item.
  ### Inputs
  Inputs content
  ### Outputs
  Outputs content
  ## Another section
  Another section content

3.2. Cucumber files - Test Cases

Every Scenario in a Cucumber file is considered to be a configuration item of type Test Case. For example:

Feature: Git-based Items

  Background:
    Given User is logged into Ketryx

  @tests:KP-456 @tests:md1-id @id:adding-glob-patterns
  Scenario: Glob patterns can be defined and properly saved when creating a new Project
    When User creates a project to manage Git-based Items with the following glob pattern
      |src/**/*.md|
      |test/**/*.md|
    And User navigates to "Settings" page
    Then User should see following glob patterns for Git-based Items:
      |src/**/*.md|
      |test/**/*.md|

  @tests:KP-789 @id:approving-git-based-items
  Scenario: Approving Git-based Items should work as expected
    When User has a project to manage Git-based Items with the following glob pattern
      |*.md|
    And User navigates to current project
    And User selects the item "Git based items"
    And User approves the selected 1 item
    Then State of "Git based items" item should be changed to "Closed"
    And User selects the item "Git based items"
    And User transitions the selected 1 item to "Resolved"
    Then State of "Git based items" item should be changed to "Resolved"
    
  @implements:KP-1011 @id:no-creating-records
  Scenario: No Records should be created if user does not opt into creating records from the Git repository's files
    When User has created a test project with the GitHub repository "Ketryx/git-based-items"
    And User navigates to current project
    Then Default placeholder text for "All items" page is shown

Metadata is defined in the tags of a Scenario. In the example above, the following tags are used:

• @tests:KP-456 - Defines traceability to another configuration item (in this case KP-456 is a Jira issue)

• @tests:md1-id - Defines traceability to another configuration item (in this case md1-id is another Git-based item)

• @id:approving-git-based-items - Defines the unique identifier of the configuration item

• @implements:KP-1011 - Defines traceability to another Test Case configuration item that already exists in Jira

@implements tag is used to reference an existing Jira Test Case. Ketryx will not create a new Test Case configuration item for the Cucumber Scenarios that use the @implements tag or the @tests tag that references already existing Jira Test Case.

In the background, Ketryx extracts and stores a testResultId property for each parsed test case. This property is used to connect automated test execution results to the test.

Main content is defined in the body of a Scenario:

• The name of the Scenario is considered to be the title of the configuration item.

• Scenario name, steps and tags are considered to be the description of the configuration item.

Traceability to other configuration items is defined in the tags of a Scenario. Every tag that starts with @tests is considered to be a traceability field, and it must always point to the item that is being tested.

If itemId is not explicitly specified, Ketryx will use the {Feature name}-{Scenario name} as a fallback. Learn more about uniquely identifying a configuration item in the section 4.

3.3. Source code - Test Cases

Define the glob pattern with the tests parser to scan the repository for files that contain test cases.

tests:src/tests/**/*.java

By defining a glob pattern with the tests parser, Ketryx will scan the repository for files that match the pattern and parse the content of the files as items of type Test Cases. Learn more about using the glob pattern metadata.

Metadata is defined in the comments above the test case function:

• Traceability to other configuration items is maintained in the comments above the test case function. A tag of the form @tests:ABC-123 can be used to associate the test with its tested items.

In the background, Ketryx extracts and stores a testResultId property for each parsed test case. This property is used to connect automated test execution results to the test. Depending on the language, the testResultId is automatically extracted and cannot be changed by the user.

Main content is defined as follows:

• Item title should be in the comment above the test case function and for that purpose, use the @itemTitle:"My Title" or @itemTitle:Title tag. If the tag is not provided, Ketryx will fall back to the function name as the item title.

• Item description is the body of the test case function.

Rules for maintaining item properties in the comments above the test case functions:

• Ketryx supports defining item properties in the first preceding block comment above the test case function

• Ketryx supports defining item properties in multiple consecutive line comments above the test case function

3.3.1. Java

    package com.example;
    
    class MyTest {
        // @itemTitle:"Title of the item" @tests:ABC-123
        // @tests:ABC-456
        @Test
        public void testAddition() {
            assertEquals(4, 2 + 2);
        }

        /**
        * @itemTitle:"Title of the item"
        * @tests:ABC-789 @tests:ABC-1011
        */
        @Test
        public void testSubtraction() {
            assertEquals(0, 2 - 2);
        }
    }

Ketryx will consider extracting the item as a Test Case only if all the following conditions are met:

• The test case function is a class method

• The test case function is annotated with the @Test annotation

• The test case function has a comment (a block comment or multiple line comments) above it that contains at least one @tests tag

3.3.2. Kotlin

    package com.example
    
    class MyTest {
        // @itemTitle:"Title of the item" @tests:ABC-123
        // @tests:ABC-456
        @Test
        fun testAddition() {
            assertEquals(4, 2 + 2)
        }

        /**
        * @itemTitle:"Title of the item"
        * @tests:ABC-789 @tests:ABC-1011
        */
        @Test
        fun testSubtraction() {
            assertEquals(0, 2 - 2)
        }
    }

Ketryx will consider extracting the item as a Test Case only if all the following conditions are met:

• The test case function is a class method

• The test case function is annotated with the @Test annotation

• The test case function has a comment (a block comment or multiple line comments) above it that contains at least one @tests tag

3.3.3. Swift

    import XCTest
    
    class MyTest: XCTestCase {
        /// @itemTitle:"Title of the item" @tests:ABC-123
        /// @tests:ABC-456
        func testAddition() {
            XCTAssertEqual(4, 2 + 2)
        }

        /**
        * @itemTitle:"Title of the item"
        * @tests:ABC-789 @tests:ABC-1011
        */
        func testSubtraction() {
            XCTAssertEqual(0, 2 - 2)
        }
    }

Ketryx will consider extracting the item as a Test Case only if all the following conditions are met:

• The class is a subclass of XCTestCase

• The test case function has a comment (a block comment or multiple line comments) above it that contains at least one @tests tag

4. Uniquely identifying a configuration item

As mentioned in the previous sections, metadata is used to uniquely identify a configuration item. The itemId field is used for this purpose. The itemId field is a string that uniquely identifies a configuration item within a Git repository. For use cases where you need to define traceability between items within a Git repository, you would need to define the itemId. However, if itemId is not explicitly specified, Ketryx will use an implicit default based on the file type and source code type, to assign the itemId to your configuration item. Learn more about how Ketryx assigns itemId based on the file type and source code type in the Defining configuration items section.

The user should take care that itemId is unique within the Git repository and Ketryx project.

4.1. How Ketryx deterministically de-duplicates items with the same itemId

When Ketryx scans a Git repository for configuration items, it will check if the itemId of the configuration item is unique within the repository. If the itemId is not unique, Ketryx will deterministically use the file path within the Git repository to choose the file from which the item will be extracted. When introducing two items with the same itemId in the same commit or adding a new item with an existing itemId in a new commit, Ketryx will sort the files by their path and choose the first file in the sorted list. The consequence of this could be that the item is extracted from a different file than the user intended. If the itemId is duplicated in the same file, Ketryx will extract the item from the first occurrence of the itemId.

5. Configuration item types

Configuration item types are used to define the type of configuration item. The itemType field is used for this purpose and following values can be used:

Requirement
Software Item Spec
Hardware Item Spec
Task
Test Case
Test Execution
Anomaly
Complaint
Change Request
CAPA
Risk

6. Traceability to other configuration items

Traceability to other configuration items is used to define the relationship between configuration items. Depending on the configuration item type, different fields are used for this purpose. Here is the list of all possible fields that can be used for traceability:

itemAffects
itemContainsTests
itemFoundAnomaly
itemFulfills
itemHasParent
itemHasRootCause
itemImplements
itemIntroducesRisk
itemIsRiskControlledBy
itemExecutes
itemRelatesTo
itemIsRelatedTo
itemResolvedBy
itemResultsIn
itemTests
itemUses
itemTriggers
itemIsTriggeredBy

Please check the Work Instructions section for each configuration item type for more information on how to use these fields.

6.1. Git-based configuration items traceability to Jira-based configuration items

In a Markdown file, it is possible to define traceability between Git-based and Jira-based configuration items. For example, it is possible to define that a Software Item Spec, whose content is managed in a Git repository, fulfills a Requirement that is managed in Jira. In order to do this, define the itemFulfills field in the metadata of the Software Item Spec, with the itemFulfills field being set to the Jira issue key:

---
itemFulfills: KP-42
itemHasParent: KP-40
---

For Cucumber and source code files that extract items of type Test Case, it is enough to use the Jira issue key as a tag, e.g., @tests:KP-42.

In Cucumber files, use the @implements tag to reference an existing Jira Test Case.

6.2. Git-based configuration items traceability to other Git-based configuration items

In a Markdown file, it is possible to define traceability between Git-based configuration items. For example, it is possible to define that a Software Item Spec, whose content is managed in a Git repository, fulfills a Requirement that is also managed in the same Git repository. In order to do this, define the itemFulfills field in the metadata of the Software Item Spec, with the itemFulfills field being set to the itemId of the Requirement:

---
itemFulfills: some-unique-string-1234
itemHasParent: some-unique-string-1235
---

For Cucumber and source code files that extract items of type Test Case, it is enough to use the @tests tag with the itemId of the Requirement, e.g., @tests:some-unique-string-1234.

6.3. Jira-based configuration items traceability to Git-based configuration items

All configuration items that are managed in a Git repository and synchronized with Ketryx are automatically exposed in Jira select fields for item relations. Thus, if a configuration item is defined in a Git repository and synced with Ketryx, it will be available in the select field of the Jira issue. For example, if a Task, whose content is managed in Jira, implements a Software Item Spec that is managed in a Git repository, you can select the Software Item Spec from the Git repository in the select field of the Task issue.

7. Approval and transition flow

Because of the collaborative nature of Git repositories, it is possible that multiple users are working on the same configuration item at the same time. Having this in mind, Git-based items do not have an owner in Ketryx, thus an approval from an owner is not required.

Given that Git-based items are synchronized with Ketryx when a developer finishes their work on a configuration item, the transition flow is also different: The initial state of a Git-based configuration item in Ketryx is Resolved. Similarly to Jira-based items, Ketryx will transition a Git-based item to Closed upon full approval, or back from Closed to Resolved if the item changes afterward.

8. Versioning

Every Git-based configuration item is associated with one or more commits in the Git repository.

Given a project version, the relevant commits are determined by the release ref pattern that is defined during the project creation or configuration process. For example, if the release ref pattern is set to refs/tags/v#, Ketryx considers the tag v1.0 to be the relevant commit for version 1.0. Hence, Git-based items found on the v1.0 tag will be considered active for version 1.0.

For incremental releases based on code change requests (e.g., GitHub pull requests), the relevant commit for the incremental release is the head of the source branch of the code change request.

Please see the source code integration guide for more information on how to work with Git repositories in Ketryx.