wrkflw - GitHub ActionsをローカルでテストできるRust製ツール

Disclaimer: This article was written by AI and may contain inaccuracies or errors. 免責事項: この記事はAIによって作成されたものであり、不正確な情報やエラーが含まれている可能性があります。

wrkflwとは

wrkflwは、GitHub ActionsのワークフローをローカルのPCで検証・実行できるRust製のコマンドラインツールです。GitHub上で実際にワークフローを動かす前に、手元の環境で動作確認ができるため、開発サイクルの高速化に貢献します。

wrkflwの特徴

wrkflwには以下のような特徴があります：

• ワークフロー検証: YAML構文と構造をチェックし、CI/CD互換の終了コードを返す
• ローカル実行: Docker、Podman、またはエミュレーションモードでワークフローを実行
• ジョブの依存関係: ジョブの依存関係を自動解決し、正しい順序で実行
• 複数のランタイム: Docker、Podman（rootless実行）、ホスト上でのエミュレーションに対応
• アクションサポート: Dockerコンテナアクション、JavaScriptアクション、複合アクション、ローカル参照に対応
• TUI: ワークフロー管理とモニタリングのためのインタラクティブなターミナルインターフェース

インストール方法

wrkflwはRustのパッケージマネージャーであるcargoを使用してインストールできます：

cargo install wrkflw

インストール後、バージョンを確認してみます：

wrkflw --version

wrkflw 0.7.3

基本的な使い方

ヘルプの確認

まず、利用可能なコマンドを確認します：

wrkflw --help

主なコマンドは以下の通りです：

• validate: ワークフローファイルの検証
• run: ワークフローをローカルで実行
• tui: TUIインターフェースを起動
• list: 利用可能なワークフローを一覧表示

簡単なワークフローを作成

実際に試してみるため、簡単なGitHub Actionsのワークフローを作成しました：

.github/workflows/simple.yml:

name: Simple Test

on:
  push:
  workflow_dispatch:

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        run: echo "Hello from wrkflw!"

      - name: Show Environment
        run: |
          echo "Running on $(uname -s)"
          echo "Current directory: $(pwd)"
          echo "Date: $(date)"

      - name: Show current user
        run: whoami

      - name: List files
        run: ls -la

      - name: Create and display file
        run: |
          echo "Testing wrkflw" > test.txt
          cat test.txt
          echo "File created successfully!"

ワークフローの検証

作成したワークフローファイルを検証します：

wrkflw validate .github/workflows/simple.yml

Validating GitHub workflow file: .github/workflows/simple.yml... Validating 1 workflow file(s)...
✅ Valid: .github/workflows/simple.yml

Summary: 1 valid, 0 invalid

構文エラーのあるファイルを検証した場合は、以下のように具体的なエラー内容が表示されます：

❌ Error processing .github/workflows/syntax-error.yml: Invalid YAML: could not find expected ':' at line 14 column 11, while scanning a simple key at line 13 column 3

Summary: 0 valid, 1 invalid

ワークフローの実行

検証が成功したら、実際に実行してみます。Docker環境がない場合は、--runtime emulationオプションを使用してエミュレーションモードで実行できます：

wrkflw run --runtime emulation .github/workflows/simple.yml

✅ Workflow execution completed successfully!

Job summary:
  ✅ hello (success)
  Steps:
    ✅ Say Hello
    ✅ Show Environment
    ✅ Show current user
    ✅ List files
    ✅ Create and display file

すべてのステップが成功しました！

詳細な出力を確認

--verboseフラグを付けると、より詳細な実行ログを確認できます：

wrkflw --verbose run --runtime emulation .github/workflows/simple.yml

[23:34:41] ℹ️ Verbose mode enabled
[23:34:41] ℹ️ Running GitHub workflow at: .github/workflows/simple.yml
[23:34:41] ℹ️ Executing workflow: .github/workflows/simple.yml
[23:34:41] ℹ️ Runtime: Emulation
[23:34:41] ℹ️ Executing job: hello
[23:34:41] ℹ️   Executing step: Say Hello
[23:34:41] ℹ️ Executing command in container: bash -c echo "Hello from wrkflw!"
[23:34:41] ℹ️ Working directory: /github/workspace
...

このモードでは、各ステップの実行詳細、環境変数、作業ディレクトリなどの情報が表示されます。

ワークフローの一覧表示

プロジェクト内のワークフローを一覧表示することもできます：

wrkflw list

GitHub Workflows:
  - .github/workflows/simple.yml
  - .github/workflows/hello.yml
GitLab CI Pipeline: No .gitlab-ci.yml file found

ジョブの依存関係をテスト

wrkflwの強力な機能の一つが、ジョブの依存関係を自動解決して正しい順序で実行する機能です。次のようなワークフローを作成して試してみました：

.github/workflows/dependent-jobs.yml:

name: Job Dependencies Test

on:
  workflow_dispatch:

jobs:
  prepare:
    runs-on: ubuntu-latest
    steps:
      - name: Prepare environment
        run: |
          echo "Preparing environment..."
          echo "PREPARED=true" >> $GITHUB_ENV

      - name: Create output
        id: prep
        run: |
          echo "timestamp=$(date +%s)" >> $GITHUB_OUTPUT
          echo "status=ready" >> $GITHUB_OUTPUT

  build:
    runs-on: ubuntu-latest
    needs: prepare
    steps:
      - name: Build application
        run: |
          echo "Building application..."
          echo "Build complete!"

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Run tests
        run: |
          echo "Running tests..."
          echo "All tests passed!"

  deploy:
    runs-on: ubuntu-latest
    needs: [build, test]
    steps:
      - name: Deploy application
        run: |
          echo "Deploying application..."
          echo "Deployment successful!"

このワークフローは以下の順序で実行される必要があります：

1. prepare（準備）
2. build（ビルド - prepareに依存）
3. test（テスト - buildに依存）
4. deploy（デプロイ - buildとtestの両方に依存）

実行してみます：

wrkflw run --runtime emulation .github/workflows/dependent-jobs.yml

✅ Workflow execution completed successfully!

Job summary:
  ✅ prepare (success)
  Steps:
    ✅ Prepare environment
    ✅ Create output
  ✅ build (success)
  Steps:
    ✅ Build application
  ✅ test (success)
  Steps:
    ✅ Run tests
  ✅ deploy (success)
  Steps:
    ✅ Deploy application

ジョブが正しい順序で実行されました！

使用してみた感想

wrkflwを実際に使ってみて、以下の点が印象的でした：

良かった点

1. セットアップが簡単: cargo install一つでインストールでき、すぐに使い始められる
2. 検証機能が便利: 構文エラーを具体的に指摘してくれるため、問題の特定が容易
3. エミュレーションモード: Docker環境がなくても基本的なワークフローを実行できる
4. ジョブ依存関係の処理: 複雑な依存関係も正しく解決してくれる
5. 分かりやすい出力: 実行結果が視覚的に分かりやすく表示される

制限事項

ドキュメントによると、以下の機能には対応していません：

• 暗号化されたシークレット
• GitHubの専用キャッシング機能
• API統合
• Windows/macOSランナー
• 手動ディスパッチ以外のイベントトリガー
• 再利用可能なワークフローからの出力伝播（未完全）
• プライベートリポジトリへのアクセス（リモート呼び出し時）

エミュレーションモードでは、actions/setup-node@v3のような公式アクションも完全にはサポートされていない場合があります。より本格的なテストには、DockerまたはPodmanランタイムの使用が推奨されます。

どのような場面で役立つか

wrkflwは以下のような場面で特に有用だと感じました：

1. ワークフロー開発時: GitHub上でコミット・プッシュを繰り返す前に、ローカルで動作確認できる
2. 構文チェック: CI/CDパイプラインを実行する前に、YAML構文の妥当性を確認できる
3. 学習目的: GitHub Actionsの動作を理解するために、手軽に実験できる
4. デバッグ: ワークフローが失敗した際、ローカルで再現して原因を特定できる

特に、GitHub Actionsの無料枠を気にせずに試行錯誤できる点が魅力的です。

まとめ

wrkflwは、GitHub Actionsのワークフローをローカル環境で手軽に検証・実行できる便利なツールです。Rust製で動作も軽快で、インストールも簡単です。完全な機能サポートには制限がありますが、基本的なワークフローの開発・テストには十分な機能を備えています。

GitHub Actionsを頻繁に使用する開発者であれば、開発フローに取り入れることで効率が向上する可能性があります。

参考リンク

• wrkflw - GitHub Repository
• GitHub Actions Documentation

検証環境

本記事で使用したパッケージのバージョン：

• wrkflw: 0.7.3
• Rust: 1.91.0
• Cargo: 1.91.0