Skip to content

feat: Add workflow dependencies visualization (#26062)#36248

Merged
wxiaoguang merged 46 commits intogo-gitea:mainfrom
xDarkmanx:feature/workflow-graph
Feb 23, 2026
Merged

feat: Add workflow dependencies visualization (#26062)#36248
wxiaoguang merged 46 commits intogo-gitea:mainfrom
xDarkmanx:feature/workflow-graph

Conversation

@xDarkmanx
Copy link
Copy Markdown
Contributor

@xDarkmanx xDarkmanx commented Dec 26, 2025 •
edited
Loading

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)

Multi-Level Pipeline
Pipeline Source

Example 2: Microservices Deployment with Matrix Jobs

Microservices Pipeline
Pipeline Source

Example 3: Real production workflow

Production Example
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

@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Dec 26, 2025
@github-actions github-actions bot added modifies/api This PR adds API routes or modifies them modifies/go Pull requests that update Go code modifies/frontend labels Dec 26, 2025
@xDarkmanx xDarkmanx force-pushed the feature/workflow-graph branch from 9e8feef to f685d5f Compare December 26, 2025 07:23
@xDarkmanx
feat: Add workflow dependencies visualization
438ac5a 
    ## API changes:
    - Add job_id field for YAML job identifiers
    - Add needs field for job dependencies
    - Update swagger documentation

    ## Frontend features:
    - Interactive graph with zoom/pan navigation
    - Matrix jobs visualization
    - Custom job names support via job_id
    - Status-based coloring and animations
    - Hover highlighting for related jobs
    - Click to navigate to job details

    ## Technical details:
    - Uses existing database columns (no schema changes)
    - Backward compatible (omitempty for new fields)
    - Handles edge cases (cycles, missing dependencies)
    - Performance optimized

    ## UI integration:
    - Updated RepoActionView.vue styles for proper theme compatibility
    - Consistent styling with Gitea's CSS variables
@xDarkmanx
fix: Resolve all linting errors with correct CSS variables
f685d5f
@xDarkmanx xDarkmanx mentioned this pull request Dec 26, 2025
Closed
ChristopherHX
ChristopherHX reviewed Dec 27, 2025
View reviewed changes
@ChristopherHX ChristopherHX added the topic/gitea-actions related to the actions of Gitea label Dec 27, 2025
@lautriva
Copy link
Copy Markdown

lautriva commented Dec 27, 2025

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

@xDarkmanx
Copy link
Copy Markdown
Contributor Author

xDarkmanx commented Dec 27, 2025

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.

@bircni
Copy link
Copy Markdown
Member

bircni commented Jan 25, 2026

Is there a plan on when to continue here? looking forward to see this in prod

@bircni
Copy link
Copy Markdown
Member

bircni commented Jan 29, 2026

@xDarkmanx @lunny what is needed to get this in for 1.26?
Would really like to help and see this as soon as possible 😄

@xDarkmanx
Copy link
Copy Markdown
Contributor Author

xDarkmanx commented Jan 29, 2026

@xDarkmanx @lunny what is needed to get this in for 1.26? Would really like to help and see this as soon as possible 😄

Apparently the community doesn't need this functionality.
But I'm willing to continue development and discussion.

@bircni
Copy link
Copy Markdown
Member

bircni commented Jan 29, 2026

@xDarkmanx I would really love to see this - i think its pretty useful

@xDarkmanx
Copy link
Copy Markdown
Contributor Author

xDarkmanx commented Jan 29, 2026 •
edited
Loading

I would really love to see this - i think its pretty useful

I completely agree with you.

You can already try this functionality.

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

@xDarkmanx
Merge branch 'main' into feature/workflow-graph
39d9a64 
Signed-off-by: Semenets V. Pavel <p.semenets@gmail.com>
@lunny
Copy link
Copy Markdown
Member

lunny commented Jan 29, 2026

Looks amazing, I need some time to review it.

@bircni
Copy link
Copy Markdown
Member

bircni commented Jan 29, 2026

Thanks @lunny 😊
Can we still get it into 1.26?

@xDarkmanx
Copy link
Copy Markdown
Contributor Author

xDarkmanx commented Feb 6, 2026

@lunny
Maybe there is something else I need to improve?

@wxiaoguang
Copy link
Copy Markdown
Contributor

wxiaoguang commented Feb 23, 2026 •
edited
Loading

Made some changes.

  1. These UI elements are removed, because without them, the UI is still clear enough.

Redundant UI elements only make users spend more time to read.

Details image
  1. Use SvgIcon for buttons and fine-tune some CSS styles
  2. "mousewheel to zoom" is removed. It only interrupts user's scrolling. Mouse wheel can't be used for zooming in many cases.
  3. (and various other fixes)

TODO (fixed)

It seems that some edges are not displayed

(not caused by my code, old code also doesn't display it):

Details

These are not used

Details image

@github-actions github-actions bot removed the modifies/api This PR adds API routes or modifies them label Feb 23, 2026
@wxiaoguang
Copy link
Copy Markdown
Contributor

wxiaoguang commented Feb 23, 2026 •
edited
Loading

There are too many problems in code.

I don't want to spend more time to guess why the code was written as that. I removed all the unclear and non-working code.

If anything is missing, feel free to add them back and make sure they really work (in following up PRs)

@wxiaoguang
Copy link
Copy Markdown
Contributor

wxiaoguang commented Feb 23, 2026

Looks amazing, I need some time to review it.

@lunny Have you really reviewed? Or just a "rubberstamp" approval?

@wxiaoguang wxiaoguang added the type/feature Completely new functionality. Can only be merged if feature freeze is not active. label Feb 23, 2026
@wxiaoguang wxiaoguang enabled auto-merge (squash) February 23, 2026 13:11
@GiteaBot GiteaBot added lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. and removed lgtm/need 1 This PR needs approval from one additional maintainer to be merged. labels Feb 23, 2026
@wxiaoguang wxiaoguang merged commit a850526 into go-gitea:main Feb 23, 2026
26 checks passed
@xDarkmanx xDarkmanx deleted the feature/workflow-graph branch February 23, 2026 22:55
@xDarkmanx
Copy link
Copy Markdown
Contributor Author

xDarkmanx commented Feb 24, 2026

@lunny @bircni @wxiaoguang

Colleagues, thank you for the thorough review and feedback. I understand the code raised some concerns, but thanks to your review it became much better.

I'm honored to be part of the community, as this is my first contribution.

zjjhot added a commit to zjjhot/gitea that referenced this pull request Feb 25, 2026
@zjjhot
Merge remote-tracking branch 'giteaofficial/main'
725a936 
* giteaofficial/main:
  Fix path resolving (go-gitea#36734)
  [skip ci] Updated translations via Crowdin
  Fix track time list permission check (go-gitea#36662)
  Fix incorrect setting loading order (go-gitea#36735)
  Use case-insensitive matching for Git error "Not a valid object name" (go-gitea#36728)
  feat: Add workflow dependencies visualization (go-gitea#36248)
silverwind added a commit to silverwind/gitea that referenced this pull request Feb 26, 2026
@silverwind
Merge branch 'main' into dropdowncss
0be7aea 
* main: (24 commits)
  Instance-wide (global) info banner and maintenance mode (go-gitea#36571)
  Add created_by filter to SearchIssues (go-gitea#36670)
  Inline and lazy-load EasyMDE CSS, fix border colors (go-gitea#36714)
  Fix release draft access check logic (go-gitea#36720)
  Change image transparency grid to CSS (go-gitea#36711)
  Avoid opening new tab when downloading actions logs (go-gitea#36740)
  Add validation constraints for repository creation fields (go-gitea#36671)
  Fix SVG height calculation in diff viewer (go-gitea#36748)
  Fix path resolving (go-gitea#36734)
  [skip ci] Updated translations via Crowdin
  Fix track time list permission check (go-gitea#36662)
  Fix incorrect setting loading order (go-gitea#36735)
  Use case-insensitive matching for Git error "Not a valid object name" (go-gitea#36728)
  feat: Add workflow dependencies visualization (go-gitea#36248)
  Add keyboard shortcuts for repository file and code search (go-gitea#36416)
  Refactor text utility classes to Tailwind CSS (go-gitea#36703)
  Prevent redirect bypasses via backslash-encoded paths (go-gitea#36660)
  Fix force push time-line commit comments of pull request (go-gitea#36653)
  Fix get release draft permission check (go-gitea#36659)
  Move `X_FRAME_OPTIONS` setting from `cors` to `security` section (go-gitea#30256)
  ...

# Conflicts:
#	web_src/css/base.css
#	web_src/css/index.css
@wxiaoguang wxiaoguang mentioned this pull request Mar 8, 2026
Closed
@wxiaoguang wxiaoguang mentioned this pull request Mar 28, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ChristopherHX ChristopherHX ChristopherHX left review comments

@lunny lunny lunny approved these changes

@wxiaoguang wxiaoguang wxiaoguang approved these changes

+1 more reviewer

@bircni bircni bircni left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. modifies/frontend modifies/go Pull requests that update Go code modifies/templates This PR modifies the template files topic/gitea-actions related to the actions of Gitea type/feature Completely new functionality. Can only be merged if feature freeze is not active.

Projects

None yet

Milestone

1.26.0

Development

Successfully merging this pull request may close these issues.

7 participants

@xDarkmanx @lautriva @bircni @lunny @wxiaoguang @ChristopherHX @GiteaBot