https://github.com/bigbag/actix
TUI application for monitoring and triggering GitHub Actions workflows. View runs, logs, and trigger workflow_dispatch — all from your terminal.
https://github.com/bigbag/actix
bubbletea cli devops github-actions github-api golang tui workflow
Last synced: about 1 month ago
JSON representation
TUI application for monitoring and triggering GitHub Actions workflows. View runs, logs, and trigger workflow_dispatch — all from your terminal.
- Host: GitHub
- URL: https://github.com/bigbag/actix
- Owner: bigbag
- License: mit
- Created: 2026-01-16T04:47:44.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-01-19T05:40:30.000Z (2 months ago)
- Last Synced: 2026-01-25T20:41:47.879Z (about 2 months ago)
- Topics: bubbletea, cli, devops, github-actions, github-api, golang, tui, workflow
- Language: Go
- Homepage:
- Size: 588 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# actix
[](https://github.com/bigbag/actix)
[](https://github.com/bigbag/actix/actions/workflows/build.yaml)
[](https://github.com/bigbag/actix/releases/latest)
[](https://github.com/bigbag/actix/blob/master/LICENSE)
A lightweight, self-hosted web UI for GitHub Actions — inspired by Jenkins. Monitor workflow runs, view stage pipelines, trigger builds, and browse logs, all from a dark-themed dashboard with sidebar navigation and breadcrumbs.
## Screenshots
### Dashboard
Project table grouped by repository with status circles, last success/failure times, and one-click build triggers.
### Workflow Runs
Build history sidebar with status indicators, full runs table with branch, commit, duration, and actor details.
### Stage View
Jenkins-style stage grid showing job status with colored cells. Run metadata (branch, commit, actor, duration) displayed above.
### Logs
Inline log viewer below the stage grid — click any stage cell to load job logs.
### Build with Parameters
Trigger workflow dispatches with dynamic input forms, branch/tag selection, and sidebar navigation.
## Features
- **Jenkins-style layout** — Sidebar navigation, breadcrumb bar, stage view grid
- **Repository groups** — Organize workflows by project groups in the sidebar
- **Dashboard** — Status circles, last success/failure, duration, play button per workflow
- **Stage View** — Visual job grid with colored status cells (click to view logs)
- **Build with Parameters** — Trigger workflow_dispatch with dynamic input forms and branch/tag selection
- **Build history** — Sidebar list with status indicators and run numbers
- **Auto-refresh** — Configurable HTMX-powered polling with loading indicator
- **Cancel / Rerun** — Cancel running workflows or rerun completed ones
- **Open in GitHub** — Quick links to GitHub Actions UI
- **Dark theme** — Full dark color scheme
## Quick Start
1. Get a GitHub token (see [GitHub Token Setup](#github-token-setup))
2. Create config file at `~/.config/actix/config.json`:
```json
{
"github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"refresh_interval": 30,
"auto_refresh": true,
"port": 9808,
"groups": [
{
"name": "Work Projects",
"repositories": ["org/repo-one", "org/repo-two"]
}
]
}
```
3. Build and run:
```bash
make build
./bin/actix
```
4. Open http://localhost:9808 in your browser.
Or use a custom config file or override the port:
```bash
./bin/actix --config /path/to/config.json
./bin/actix -c /path/to/config.json # shorthand
./bin/actix --port 3000 # override port
./bin/actix -p 3000 # shorthand
```
Or set `GITHUB_TOKEN` environment variable (takes priority over config file):
```bash
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
./bin/actix
```
## Installation
```bash
# Clone the repository
git clone https://github.com/bigbag/actix.git
cd actix
# Build (requires templ CLI: go install github.com/a-h/templ/cmd/templ@latest)
make build
# Or install to GOPATH/bin
make install
```
## GitHub Token Setup
actix requires a GitHub Personal Access Token to access the GitHub API.
### Creating a Fine-grained Token (Recommended)
1. Go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/tokens?type=beta)
2. Click **Generate new token**
3. Set a descriptive name (e.g., "actix")
4. Set expiration as needed
5. Under **Repository access**, select the repositories you want to monitor
6. Under **Permissions > Repository permissions**, grant:
- **Actions**: Read and write (to view runs and trigger workflows)
- **Contents**: Read-only (to read workflow files for inputs)
- **Metadata**: Read-only (required)
7. Click **Generate token**
8. Copy the token (starts with `github_pat_`)
### Creating a Classic Token
1. Go to [GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)](https://github.com/settings/tokens)
2. Click **Generate new token (classic)**
3. Set a descriptive name
4. Select scopes:
- `repo` - Full control of private repositories (or `public_repo` for public only)
- `workflow` - Update GitHub Action workflows
5. Click **Generate token**
6. Copy the token (starts with `ghp_`)
### Token Storage
You can provide the token in two ways:
1. **Environment variable** (recommended for security):
```bash
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
2. **Config file** at `~/.config/actix/config.json`:
```json
{
"github_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```
The environment variable takes priority if both are set.
## Configuration
### CLI Flags
- `--config`, `-c` - Path to config file (default: `~/.config/actix/config.json`)
- `--port`, `-p` - Web server port (overrides config file value)
### Config File
Default location: `~/.config/actix/config.json`
```json
{
"github_token": "ghp_xxx...",
"refresh_interval": 30,
"auto_refresh": true,
"port": 9808,
"groups": [
{
"name": "Work Projects",
"repositories": ["org/repo-one", "org/repo-two"]
},
{
"name": "Personal",
"repositories": ["username/my-project"]
}
]
}
```
- `github_token` (string, required) - GitHub Personal Access Token
- `refresh_interval` (int, default: 30) - Auto-refresh interval in seconds
- `auto_refresh` (bool, default: true) - Enable auto-refresh
- `port` (int, default: 9808) - HTTP server port
- `groups` (array, required) - Repository groups
- `name` (string, required) - Group name (shown in sidebar)
- `repositories` (array, required) - List of `owner/repo` strings
## Make Commands
```bash
make build # Build binary to bin/actix (generates templ + compiles)
make run # Build and run
make run/quick # Run without rebuild
make test # Run tests
make vet # Run go vet
make tidy # Tidy Go modules
make templ # Generate templ templates
make clean # Remove build artifacts
make install # Install to GOPATH/bin
make build-all # Build for linux/darwin amd64/arm64
```
## Testing
The project includes unit tests for major components.
### Running Tests
```bash
# Run all tests
make test
# Run tests with verbose output
go test -v ./...
# Run tests with coverage
go test -cover ./...
# Run specific package tests
go test -v ./internal/github/...
go test -v ./internal/config/...
```
### Test Coverage
Tests cover the following areas:
- **internal/github** - Repository parsing, duration formatting, URL building, tag fetching
- **internal/config** - Configuration loading, validation, environment variable overrides
Tests run automatically in CI before builds on pull requests and releases.
## Troubleshooting
### 404 Not Found errors
If you see `404 Not Found (check token permissions)`:
1. **Fine-grained token**: You must explicitly grant access to each repository:
- Go to https://github.com/settings/tokens?type=beta
- Edit your token
- Under **Repository access**, select the specific repositories
- Under **Permissions > Repository permissions**, ensure **Actions** has "Read" access
2. **Classic token**: Ensure you have the `repo` scope selected
3. **Private organization repos**: Your token must have access to the organization. Contact your org admin if needed.
### 401 Unauthorized errors
Your token is invalid or expired:
- Generate a new token at https://github.com/settings/tokens
- Update your config or environment variable
### 403 Forbidden errors
Either rate limited or access denied:
- Wait a few minutes if rate limited
- Check that your token has correct permissions
- For organization repos, ensure SSO is authorized if required
### Viewing logs
actix writes detailed logs to `~/.config/actix/actix.log`:
```bash
# Follow logs in real-time
tail -f ~/.config/actix/actix.log
# View recent logs
cat ~/.config/actix/actix.log
```
### Repository format
Repositories in config can be specified as:
- `owner/repo` (recommended)
- `owner/repo/` (trailing slash OK)
- `https://github.com/owner/repo` (full URL OK)
## License
MIT License - see [LICENSE](LICENSE) file.