• Motivation
  • Goals
  • Non-Goals
• Proposal
• Implementation Details
• Design Details
  • REST Structure
    • File Structure
    • Properties
  • GraphQL Structure
    • Current File Structure
    • Current Properties
    • Considerations
      • Properties
      • Query Structure
      • Directory Structure
• Future Improvements

Pipeline Mini Graph

This blueprint serves as living documentation for the Pipeline Mini Graph. The Pipeline Mini Graph is used in various places throughout the platform to communicate to users the status of the relevant pipeline. Users are able to re-run jobs directly from the component or drilldown into said jobs and linked pipelines for further investigation.

Motivation

While the Pipeline Mini Graph primarily functions via REST, we are updating the component to support GraphQL and subsequently migrating all instances of this component to GraphQL. This documentation will serve as the SSOT for this refactor. Developers have expressed difficulty contributing to this component as the two APIs co-exist, so we need to make this code easier to update while also supporting both REST and GraphQL. This refactor lives behind a feature flag called ci_graphql_pipeline_mini_graph.

Goals

• Improved maintainability
• Backwards compatibility
• Improved query performance
• Deprecation of REST support

Non-Goals

• Redesign of the Pipeline Mini Graph UI

Proposal

To break down implementation, we are taking the following steps:

1. Separate the REST version and the GraphQL version of the component into 2 directories called pipeline_mini_graph and legacy_pipeline_mini_graph. This way, developers can contribute with more ease and we can easily remove the REST version once all apps are using GraphQL.
2. Finish updating the newer component to fully support GraphQL
3. Optimize GraphQL query structure to be more performant.
4. Roll out ci_graphql_pipeline_mini_graph to globally enable GraphQL instances of the component.

Implementation Details

Design Details

REST Structure

File Structure

├── pipeline_mini_graph/
├── └── legacy_pipeline_mini_graph/
│       ├── legacy_job_item.vue
│       ├── legacy_linked_pipelines_mini_list.vue
│       ├── legacy_pipeline_mini_graph.vue
│       ├── legacy_pipeline_stage.vue
│       └── legacy_pipeline_stages.yml

All data for the legacy pipeline mini graph is passed into the REST instance of the component. This data comes from various API calls throughout different apps which use the component.

Properties

GraphQL Structure

The GraphQL instance of the pipeline mini graph has self-managed data.

Current File Structure

├── pipeline_mini_graph/
|   ├── job_item.vue
│   ├── linked_pipelines_mini_list.vue
│   ├── pipeline_mini_graph.vue
│   ├── pipeline_stage.vue
│   └── pipeline_stages.yml
├── ├── graphql/
│       ├── get_pipeline_stage_query.query.graphql
│       └── get_pipeline_stages_query.query.graphql

Current Properties

Considerations

Properties

• isMergeTrain: This property is specific to the MR page and is used to display a message in the job dropdown to warn users that merge train jobs cannot be retried. This is an odd flow. Perhaps we should consider either having this data come from somewhere else within the pipeline mini graph, or living in the merge train widget itself. It is worth noting here that this boolean is not used for any other logic outside of displaying this message.

• pipelineEtag: Consider whether this data must be passed into the pipeline mini graph, or whether we can generate this within the component through a query.

Query Structure

Currently the approach is to use 2 queries in the parent file

• getPipelineStages: populates the stages of the current pipeline
• getLinkedPipelines: if there is an upstream pipeline or any downstream pipelines, this query will populate those

Another query called getPipelineStage will be used to populate the dropdown when a stage icon is clicked.

We need to consider whether this is the most performant way to query for the mini graph.

Should pipeline stages and linked pipelines populate in 2 separate queries or is it okay to just have a single query for all icons and statuses in the mini graph to be displayed? Considerations below:

• The reason this is currently split is because the upstream/downstream sections of the mini graph were added as a feature enhancement after the initial component already existed and they used to be a premium feature. Since we have restructured this to all exist as free, we should reconsider.
• The pmg exists in several pipelines lists, so there will be up to 15 on a page rendering at a time.
• Since we have not implemented subscriptions, we are still using polling to update this component.
• If we merge two queries, do we hit maximum complexity or not?
• Loading time and the UI: What information do we want to render the fastest? Can we defer some information to load with the second query?

Directory Structure

There has been an interest in more information from downstream pipelines. As such, we may want to consider rethinking linked_pipelines_mini_list.vue and having the downstream pipelines into their own file called downstream_pipelines.vue instead. The upstream pipeline could then be rendered with a simple ci-icon.

Future Improvements

• GraphQL Subscriptions
• Show downstream pipeline jobs
• Possible redesign