actup

Keep your GitHub Actions up to date — interactively, safely, and fast.

Report Bug · Request Feature

---

actup scans your GitHub Actions workflows and upgrades action references to their latest versions. Pick upgrades interactively via a terminal UI, or run it non-interactively in CI. It detects known breaking changes between major versions and warns you before upgrading.

Quick Start

# Interactive mode — review and select upgrades in a TUI
actup

# Non-interactive mode — upgrade everything automatically
actup --no-tui

# Preview changes without touching files
actup --dry-run

Features

• Workflow discovery — recursively finds .yml / .yaml files under .github/workflows/
• Interactive TUI — Bubble Tea–powered checklist with select-all, per-action toggle, and breaking-change detail view
• Non-interactive mode — --no-tui upgrades everything; prompts on TTY for breaking changes (override with --force)
• Breaking-change detection — embedded registry of known breaking changes between major versions
• Major-tag or full semver — default resolves v5-style tags; --semver opts into v5.3.1 pinning
• Dry-run — --dry-run previews a diff without touching files
• Atomic writes — temp-file + rename prevents partial updates
• Concurrent API — up to 5 parallel GitHub requests with in-memory caching
• GitHub CLI fallback — auto-discovers tokens from gh auth token when no env var is set
• Config file — optional .actup.yaml for per-action pins, overrides, and exclusions

Demo

Table of Contents

• Quick Start
• Installation
• Usage
• AI Skill
• Configuration
• Pre-commit Hooks
• Breaking Changes
• Roadmap
• Contributing
• License
• Acknowledgments

Installation

Package Managers

Homebrew (macOS & Linux):

brew tap lynicis/tap
brew install actup

Scoop (Windows):

scoop bucket add actup https://github.com/lynicis/scoop-bucket.git
scoop install actup

Go install:

go install github.com/lynicis/actup@latest

Debian / Ubuntu:

curl -LO https://github.com/lynicis/actup/releases/latest/download/actup_latest_linux_amd64.deb
sudo dpkg -i actup_latest_linux_amd64.deb

Fedora / RHEL / CentOS:

curl -LO https://github.com/lynicis/actup/releases/latest/download/actup_latest_linux_amd64.rpm
sudo rpm -i actup_latest_linux_amd64.rpm

Replace amd64 with arm64 for ARM systems.

Docker

Images are published to ghcr.io/lynicis/actup for linux/amd64 and linux/arm64:

# Show help
docker run --rm ghcr.io/lynicis/actup:latest --help

# Scan current directory
docker run --rm -v "$PWD:/workdir" -w /workdir ghcr.io/lynicis/actup:latest

# With GitHub token for higher rate limits
docker run --rm -v "$PWD:/workdir" -w /workdir \
  -e GITHUB_TOKEN \
  ghcr.io/lynicis/actup:latest

Build from Source

Requires Go 1.26 or later.

git clone https://github.com/lynicis/actup.git
cd actup
make build
make install   # optional, installs to $GOPATH/bin

Pre-built Binaries

Download binaries for Linux, macOS, or Windows from the Releases page.

Usage

Run actup from the root of any repository with GitHub Actions workflows:

# Interactive mode (default) — opens TUI to select upgrades
actup

# Non-interactive mode — upgrades all actions automatically
actup --no-tui

# Preview changes without writing files
actup --dry-run

# Use full semver tags instead of major tags (e.g., v5.3.1 instead of v5)
actup --semver

# Force upgrades past known breaking changes (non-interactive mode)
actup --no-tui --force

# Scan custom paths
actup -p ./my-workflows -p ./another-path

# Provide a GitHub token for higher rate limits (5,000 req/hr vs 60)
actup -t $GITHUB_TOKEN
# or set the environment variable
export GITHUB_TOKEN=ghp_xxx
actup

AI Skill

You can also use actup's workflow-upgrading logic as an Agent Skill in compatible AI coding agents (Claude Code, OpenCode, Cursor, etc.).

Install

Via gh skill (agentskills.io):

gh skill install lynicis/actup github-actions-updater

Via npx skills (skills.sh):

npx skills add lynicis/actup --skill github-actions-updater

Usage

Once installed, ask your agent:

"Update my GitHub Actions" "Which actions are out of date?" "Bump actions in my workflows"

The skill scans your .github/workflows/*.yml files, resolves the latest version of each action from GitHub, warns about known breaking changes, and produces a diff-style report with suggested upgrades. It does not edit files unless you explicitly ask.

Configuration

GitHub Token Resolution

actup resolves GitHub tokens in this order:

1. --token flag
2. GITHUB_TOKEN environment variable
3. gh auth token from the GitHub CLI

Authenticated requests get 5,000 API calls/hour vs 60 for unauthenticated. To set up gh:

gh auth login

Config File (.actup.yaml)

Place an optional .actup.yaml in your project root for persistent overrides. Editors supporting YAML language servers will provide autocomplete and validation if you add the $schema directive:

# yaml-language-server: $schema=https://raw.githubusercontent.com/lynicis/actup/main/schema.json

# Global default major version (overridden by --semver flag)
major: 4

# Per-action overrides
actions:
  actions/checkout: 4           # pin to latest v4.x.x
  actions/setup-go: v5.3.0     # pin to exact version
  some-org/some-action: skip   # exclude from upgrades

Precedence: CLI flags > config file > built-in defaults.

Pre-commit Hooks

Catch stale action versions before they land in a commit — two options:

actup install-hooks (built-in)

Installs a plain pre-commit hook that runs actup --check --no-tui on every commit:

actup install-hooks              # install the hook
actup install-hooks --dry-run    # preview before installing
actup install-hooks -f           # overwrite existing hook
actup install-hooks --uninstall  # remove the hook

pre-commit framework

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/lynicis/actup
    rev: v0.5.0
    hooks:
      - id: actup-check

The hook runs actup --check --no-tui and fails the commit if any actions can be upgraded. Omit rev to track main for the latest version.

Breaking Changes

actup includes an embedded registry of known breaking changes between major versions. When an upgrade involves breaking changes:

• TUI mode: Shows a ⚠ breaking changes badge — press i for details
• Non-interactive mode: Prompts for confirmation on TTY, or use --force to skip prompts

The registry lives in internal/breakingchanges/registry.yaml. Contributions welcome — if you encounter a breaking change not in the registry, please open a PR.

Roadmap

• Interactive TUI with checklist selection
• Non-interactive (--no-tui) mode
• Dry-run support
• Concurrent GitHub API calls with rate-limit awareness
• Cross-platform builds (Linux, macOS, Windows)
• Pre-commit hooks for CI integration
• Major version pinning (--major)
• Config file support (.actup.yaml)
• Breaking-change detection with embedded registry
• Full semver tag resolution (--semver)
• Integration with dependabot-style grouped updates
• Pre-upgrade hooks / custom validation

See open issues for the full list of proposed features and known issues.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and lint: make test && make lint
5. Commit with a descriptive message (git commit -m 'feat: add amazing feature')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a pull request

Please ensure your code passes existing tests and follows the project's style conventions.

License

Distributed under the MIT License. See LICENSE for details.

Acknowledgments

Built with these excellent libraries:

• Bubble Tea — TUI framework
• Cobra — CLI framework
• go-github — GitHub API client
• go-yaml — YAML parser