Migrate Neos.Ui To GitHub Actions: A Comprehensive Guide

Hey folks! 👋 Let's dive into a project that's all about streamlining our development workflow for Neos.Ui. We're talking about a complete shift to GitHub Actions, ditching CircleCI and StyleCI in the process. This move is all about making our lives easier, improving our CI/CD pipelines, and setting the stage for some exciting future developments. This guide focuses on Neos.Ui versions up to 9.0, so let's get started.

The Current Landscape: A Mixed Bag 💼

Right now, Neos.Ui is a bit of a mixed bag when it comes to CI/CD. We've got a little bit of everything going on:

• GitHub Actions: We've already started using GitHub Actions with a couple of key components:

  • add-pr-labels.yml: This action helps us keep things organized by automatically labeling pull requests.
  • build_and_test.yml: This one, which was adopted from CircleCI (thanks to this PR), handles building and testing our code.

• CircleCI + SauceLabs: CircleCI is the workhorse for building a running Flow application with Neos.Ui integrated. Then, we use a Sauce Tunnel to expose our local Flow server and connect to SauceLabs. This setup allows us to run headful browser tests using TestCafe, with screen recording for debugging and verification.

  • In addition to the UI tests, the same Flow application is used to run Flow unit tests (not functional ones) and recently PHPStan for PHP code analysis. This is where we run tests to make sure that everything is running as expected.

• StyleCI: For all our PHP code style needs, we're currently relying on the external service StyleCI to handle linting and ensure our code adheres to coding standards.

The Goal: A Unified CI with GitHub Actions

The goal is simple: migrate everything to GitHub Actions. This unification will simplify our workflow, improve efficiency, and make future integrations easier. We'll still be using SauceLabs for our e2e tests because they provide excellent browser testing capabilities. So, we'll have the following actions defined to streamline the process.

Breaking Down the Actions 🛠️

Here's a breakdown of the actions we'll be setting up. These are divided by Client and Server, reflecting what they handle, and an E2E section that manages both, running a Flow server and building JavaScript for browser testing.

• Add Labels to Pull Requests: Like the existing action, this will keep our pull requests organized.
• Client (JavaScript) / Code Style: This action will ensure our JavaScript code adheres to our code style guidelines.
• Client (JavaScript) / Unit Tests: This action will run all our JavaScript unit tests.
• Server (PHP) / Lint and Test (8.2, 9.0): This will handle linting and testing our PHP code, specifically for PHP versions 8.2 and 9.0.
• Server (PHP) / Lint and Test (8.3, 9.0): Similar to above, but for PHP versions 8.3 and 9.0.
• E2E (Client, Server) / Browser Tests (8.3, 9.0): This action will run our browser tests using SauceLabs, covering PHP versions 8.3 and 9.0. It combines client and server aspects.

Why Migrate? The Advantages 🎉

So, why are we making this big change? Here are some key advantages:

• Simplified Workflow: No more logging into CircleCI to restart a job. Everything happens within the familiar GitHub interface.
• Integration with Neos Development Collection: This is a big one. A unified CI setup opens the door to merging Neos.Ui into the neos-development-collection. This is discussed in this RFC.
• Reduced Complexity: Our current CircleCI setup involves multiple intermediary steps that store and restore state, which can be difficult to debug. GitHub Actions will simplify this.
• Easier Extensibility API Tests: It will be easier to integrate tests for the upcoming extensibility API—where we need to build a plugin in the TestDistribution.

Things CircleCI Did Well (and How We'll Handle Them)

Let's give credit where it's due. CircleCI did some things pretty well, and we'll be making sure we have similar capabilities with GitHub Actions.

• Background Jobs: We'll use flow server:run & to run background jobs, which avoids output swallowing. This ensures that the background process runs smoothly and logs any errors or issues that may arise.
• SSH Debugging: For debugging, we'll use the external SSH action, which provides SSH support.

Implementation: The Roadmap 🗺️

We're following a phased approach to make this transition as smooth as possible.

• Step 1: Use GitHub CI and run behavior tests: (TASK: use GitHub ci and run behaviour tests) This step involves setting up the initial GitHub Actions workflows and getting our behavior tests running.
• Step 2: Fix-up #4008 use GitHub CI: (TASK: Fix-up #4008 use GitHub ci) In this step, we will make adjustments and refinements to the workflows to ensure they function correctly.
• Remove StyleCI: Once all the PHP code style tasks have been moved into GitHub Actions, we can get rid of StyleCI. We're not throwing StyleCI under the bus, but moving those tasks into GitHub Actions. This ensures that our code adheres to coding standards during every build.

Conclusion: Embracing the Future of Neos.Ui Development 🚀

Migrating to GitHub Actions is a significant step towards a more efficient and integrated development workflow for Neos.Ui. By unifying our CI/CD pipelines, we're simplifying our processes, improving our ability to test and deploy code, and opening up exciting opportunities for future development. The advantages are clear: a more streamlined workflow, easier integration, and a more robust testing environment.

This transition will not only improve our day-to-day work but also set the stage for deeper integration within the Neos ecosystem. As we move forward, we'll be better equipped to collaborate, test, and innovate, ensuring that Neos.Ui remains a powerful and user-friendly framework. So, let's roll up our sleeves and get started with this awesome transition! We're confident that this move will significantly benefit the entire Neos.Ui community.

Keep an eye on those pull requests and workflows. We're all in this together, so let's make it happen! 🥳