4 min read
We are excited to announce that we will be migrating your Kosli Flows data to Flows with Trails. This transition will unlock access to our latest features, such as the first-class Sonar integration, as well as upcoming ones like environment compliance policies and custom attestation types.
Legacy Flows have served us well in the early stages, where they were designed to map the value stream of producing a single software artifact. However, as our product and user base have grown, we’ve encountered the limitations of this model in tracking more complex value streams. To address these challenges, we introduced the concept of Trails.
In this new paradigm, Flows represent processes, while Trails represent chains of facts related to one instance of a process. These processes can be focused on software delivery, business operations, or a combination of both, offering greater flexibility to track the workflows that matter to you.
Since the introduction of Trails, we have been developing more advanced features on top of this structure. By migrating your data to the new model, you will seamlessly gain access to the latest Kosli capabilities and be prepared for future enhancements.
How to prepare?
No action is required on your part. All existing CLI commands and API endpoints will continue to work seamlessly, with no expected downtime. However, we encourage you to be aware of the changes to the data structure and Kosli UI that will result from this migration.
What will change?
Data structure
This migration will transform your legacy flows data to the new data model with Trails as follows:
- Legacy flow templates (a list of evidence names) will be transformed to the new flow template format. The type of the evidence will be set to “*” (any) to match the current behavior but you can later adjust this to require specific evidence types.
- A Trail will be created for each git commit associated with the artifacts you have reported. If several artifacts were reported with the same git commit, they will be joined in a single trail after the migration.
- Commit and Artifact evidence will be transformed to Attestations
Note: The contents of your artifacts and evidence data will not change. Only the structure of the data is changed. The exception to this is invalid data which was reported before we introduced strict validations (e.g. invalid URLs). Such data will be replaced by some default valid data.
API & CLI changes
Legacy V1/V2 API endpoints for reporting artifacts and evidence will convert any incoming reports to the new format on-the-fly. While these endpoints will remain functional for now, they are deprecated and will be removed in the future.
The CLI commands using deprecated API endpoints will also continue to work in the near term, but they are now deprecated.
We encourage you to plan to switch to the newer API endpoints and CLI commands in the near future. Check our migration guide.
A detailed list of the deprecated API endpoints and CLI commands is provided below
| CLI | API |
|---|---|
| kosli create flow --template … (--template flag is deprecated) |
PUT /api/v2/flows/{org} PUT /api/v1/projects/{org} (the endpoints are not deprecated but sending in the legacy template is) |
| kosli report artifact … (deprecated. Use kosli attest artifact instead) |
POST /api/v2/artifacts/{org}/{flow_name} PUT /api/v1/projects/{org}/{flow_name}/artifacts/ (artifacts require template_referemce_name and trail_name fields now, when they are not provided, we automatically create a trail from the git commit SHA1 and default the template_reference_name to “artifact”) |
| kosli report evidence artifact … (deprecated. Use kosli attest commands instead) |
POST /api/v2/evidence/{org}/artifact/{flow_name}/<type> PUT /api/v1/projects/{org}/{flow_name}/evidence/<type> POST /api/v1/projects/{org}/evidence/artifact/{flow_name}/<type> (these endpoints are deprecated. Use the attestations endpoints instead) |
| kosli report evidence commit … (deprecated. Use kosli attest commands instead) |
POST /api/v2/evidence/{org}/commit/{flow_name}/<type> PUT /api/v1/projects/{org}/commit/evidence/<type> POST /api/v1/projects/{org}/evidence/commit/<type> (these endpoints are deprecated. Use the attestations endpoints instead) |
UI Changes
After the migration is done, your Flows page will start showing Trails. We prepared a short video explaining the new UI.
Migration Timeline
The migration will occur in the following stages:
- October 29th, 2024: Migration announced.
- November 4th, 2024: Migration will be performed.
Support and Resources
To help you migrate your Kosli reporting to the newer CLI commands, we have created a brief migration guide.
If you have any questions or need assistance, please reach out to our support team support@kosli.com or via our community slack.
Get Support on our Slack Community
JoinWe appreciate your patience and understanding as we make this transition. We’re confident that it will bring significant improvements and look forward to delivering even better features in the near future. As always, we would love to hear your feedback!
