actix

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)

2. Create config file at ~/.config/actix/config.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:

make build
./bin/actix

4. Open http://localhost:9808 in your browser.

Or use a custom config file or override the port:

./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):

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
./bin/actix

Installation

# 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
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)
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):

   export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Config file at ~/.config/actix/config.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

{
  "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

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

# 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:

# 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 file.