feat: Add workflow dependencies visualization (#26062)

[xDarkmanx]

feat: Add workflow dependencies visualization

Related to #26062

What does this PR do?

This PR adds an interactive visualization component that displays job dependencies in Gitea Actions workflow runs. It helps users understand complex pipeline structures at a glance, addressing the difficulty of comprehending dependency chains in current Gitea UI.

Screenshots / Images

Example 1: Multi-level CI/CD Pipeline (9 levels deep)

Pipeline Source

Example 2: Microservices Deployment with Matrix Jobs

Pipeline Source

Example 3: Real production workflow

Pipeline Source

Docker Image for Testing

A pre-built Docker image with these changes is available for reviewers to test without building locally:

docker pull xvulturex/gitea:latest
docker run -p 3000:3000 xvulturex/gitea:latest

What changes were made?

API Changes:

• Added job_id field to structs.ActionJob for YAML job identifier mapping
• Added needs field to track job dependencies as defined in workflow YAML
• Both fields are omitempty for backward compatibility
• Updated Swagger documentation for new fields

Frontend Component:

• New Vue 3 component WorkflowGraph.vue with TypeScript support
• Interactive features: zoom with mouse wheel, pan by dragging, hover highlighting
• Visual status indicators with animations (success, failure, running, etc.)
• Support for matrix jobs through job_id field correlation
• Responsive design using CSS variables for theme compatibility
• Click navigation to job details page

Backend:

• No database schema changes required
• Uses existing columns (job_id maps to existing job_name in actions table)
• Handles edge cases: cycles, missing dependencies, invalid job references

Testing

The implementation has been thoroughly tested with:

Manual Testing:

• ✅ Simple workflows (3-5 jobs)
• ✅ Complex dependency chains (20-50+ jobs, 9+ levels deep)
• ✅ Matrix job expansions (6x2, 3x3 matrices)
• ✅ Edge cases (cycles, missing dependencies handled gracefully)
• ✅ Theme compatibility (light and dark modes)
• ✅ Mobile responsive behavior

Test Workflows Used:

1. Multi-Level CI/CD Pipeline - 9 dependency levels, parallel branches, matrix jobs
2. Microservices Deployment - Complex matrix jobs, multiple dependency paths
3. Real production workflow - Validated behavior with actual user workflow

Performance:

• Handles workflows with 20-50 jobs efficiently
• Uses requestAnimationFrame for smooth zoom/pan animations
• Optimized SVG rendering with minimal DOM updates

Backwards Compatibility

• ✅ Full backwards compatibility - New API fields are optional (omitempty)
• ✅ No breaking changes - Existing API responses unchanged
• ✅ Optional feature - Visualization only shown when dependency data is available
• ✅ Fallback behavior - No graph shown if no dependencies exist
• ✅ Database compatibility - No schema migrations required

Usage

1. Visualization appears automatically when viewing workflow runs with dependencies
2. Interactive controls:
   • Zoom: Mouse wheel or +/- buttons
   • Pan: Click and drag
   • Reset: Reset view button
3. Navigation: Click any job node to navigate to its details page
4. Visual indicators:
   • Green: Success/Completed
   • Red: Failed
   • Yellow: Running
   • Gray: Waiting/Blocked

Checklist

• Code follows the Gitea code style guidelines
• Self-reviewed the code changes
• Added necessary documentation (Swagger updates)
• Backwards compatible changes
• Considered performance implications
• Tested on mobile/responsive views
• Used CSS variables for theming
• No console errors in development mode

Additional Notes

• The graph uses a topological layout algorithm to arrange jobs by dependency levels
• Matrix jobs are properly handled via the job_id field which maps to YAML job identifiers
• All styling uses CSS variables (var(--color-*)) for proper theme integration
• The component is designed to be maintainable with clear separation of concerns
• Handles edge cases with appropriate warnings in console

[ChristopherHX]

I would revert changes to the rest api, since the UI does not use this struct. Might be a leftover from previous tries?

[xDarkmanx]

The needs and job_id fields are required for the workflow dependency graph functionality implemented in the WorkflowGraph.vue component. The component uses job_id to correctly map dependencies between jobs, especially when custom job names are used in the workflow definition. Without these fields, it is impossible to reliably determine the connections between nodes (edges will not be drawn).

[ChristopherHX]

The needs and job_id fields are required for the workflow dependency graph functionality implemented

Yes I agree that you need those information to build the graph, but you do not use the gitea rest api structs in your vue component as far as I understood.

Your template uses the data from the view model

Changes of this file
https://github.com/go-gitea/gitea/blob/f685d5f8d586f3970820e5471706fe9b08d3b315/routers/web/repo/actions/view.go

This then directly use ActionRunJob to create this data for your vue component.

Additional Context As far I know Gitea does not allow for security related reasons to use the api/v1 from the ui code, because they are not protected against webbrowser cross site attacks and so on

[xDarkmanx]

When I was developing the graph component, I considered keeping the data structures consistent between the API and the view layer. These fields might be needed for direct API usage by third-party applications, not just my component. If you think they won't be necessary, I can remove them.

[ChristopherHX]

Rest api only change as well.

[xDarkmanx]

Yes, they are affected.
However, these changes are backward compatible.
They are only required for the Dependency Graph functionality.

[ChristopherHX]

Rest api only change as well.

[xDarkmanx]

Yes, they are affected.
However, these changes are backward compatible.
They are only required for the Dependency Graph functionality.

[lautriva]

Would it be possible to show the graph "left-to-right" (like Github / Gitlab) instead of "top to bottom"?

[xDarkmanx]

Would it be possible to show the graph "left-to-right" (like Github / Gitlab) instead of "top to bottom"?

Good suggestion! I can add an orientation toggle (top-down ↔ left-right) in a separate PR to keep this one focused on the core functionality.