Rebuild and debug a failed CI run on your machine.
--- ## Why When a CI job fails, the logs show you what broke but not the state it broke in. You can re-run the job with an interactive SSH session (tmate and similar), but that means re-triggering the run and debugging a live runner that's time-limited and gone the moment the job ends. rewindr takes the other approach: when a job fails it captures the environment (your files, the environment variables, a matching runner image) into an artifact, and the CLI rebuilds it locally. You get a shell in that environment, on your machine, for as long as you need, without re-running anything. ## How it works 1. **The action** runs as a `post` step in your workflow. When the job fails it captures the workspace, the environment, and a small manifest describing the run, and uploads them as one artifact. 2. **The CLI** pulls that artifact, rebuilds the environment in Docker on a base image that mirrors the runner, mounts your code where the run expected it, and shells you in. ## Quick start ### 1. Add the action to your workflow ```yaml - uses: actions/checkout@v4 - uses: dr-alberto/rewindr@v0.1.2 with: # Lets rewindr redact secret values from the captured environment. secrets: ${{ toJSON(secrets) }} # ... the rest of your job ... ``` It only does work when the job fails, so green runs are untouched. This repo runs rewindr on its own CI if you want a working example: [.github/workflows/test-action.yml](.github/workflows/test-action.yml). ### 2. Install the CLI ```bash curl -fsSL https://raw.githubusercontent.com/dr-alberto/rewindr/main/install.sh | sh ``` Installs to `/usr/local/bin` (or `~/.local/bin` if that isn't writable). Supports macOS and Linux on x86\_64 and arm64. Alternatively, download a binary directly from [Releases](https://github.com/dr-alberto/rewindr/releases). ### 3. Authenticate ```bash rewindr login ``` You'll need a GitHub token with read access to Actions (fine-grained: _Actions: read_; classic: `repo`). It's stored locally, readable only by you. ### 4. Rewind a failure ```bash rewindr list # failed runs that have a rewindr artifact rewindr play latest # rebuild the most recent one and shell in rewindr play 1234567890 # or a specific run id ``` You land in a shell, inside the failed environment, at the workspace. ## Commands | Command | What it does | | ----------------------------------- | ------------------------------------------------------------------ | | `rewindr login` | Store a GitHub token. | | `rewindr list` | List runs that have a rewindr artifact. | | `rewindr download