プッシュする前にローカルで GitHub Actions と GitLab CI を実行する方法

自分のコンピュータで `act` を使用して GitHub Actions を実行し、gitlab-ci-local で GitLab CI を実行できます。どちらもパイプライン ファイルを読み取り、Docker コンテナで各ジョブを開始します。 Docker をインストールし、ランナーをインストールしてから、リポジトリのフォルダから act -j test または gitlab-ci-local test を実行します。失敗したジョブは、プッシュしてホストされたランナーを待った後ではなく、マシン上で数秒で失敗するようになりました。

このガイドでは、macOS、Windows、および Linux にインストールするもの、両方のランナーのコマンド、コピーできるサンプル ワークフロー、ローカル実行の制限、最初に遭遇するエラーについて説明します。このチュートリアルでは、私たちが作成した Git クライアントである GitTree を使用します。その ローカル パイプライン ページでは、インストールした内容がチェックされ、サンプル ファイルが書き込まれ、正確なコマンドが準備されます。ローカル パイプラインは GitTree の無料プランの一部であり、ホスティング アカウントは必要ありません。

CI パイプラインをローカルで実行する理由は何ですか?

ワークフロー ファイルに対するすべての変更は、実行するまでテストできないコードです。ローカル ランナーがない場合、ループは次のようになります: YAML の編集、コミット、プッシュ、ランナーの待機、ログの読み取り、繰り返し。各ラウンドには数分かかり、「再試行」のようなコミットの痕跡が残ります。ローカルで実行すると、ループが数秒に短縮され、履歴がクリーンな状態に保たれます。

必要なもの: Docker とランナー 1 人

どちらのランナーもコンテナ内のすべてのジョブを開始するため、Docker エンジンがインストールされて実行されている必要があります: macOS の Docker Desktop、OrbStack または Colima、Windows の Docker Desktop、Linux の Docker Engine または Docker Desktop。次に、ファイルのランナーをインストールします。

gitlab-ci-local を npm でインストールする場合は、Node.js 18 以降が必要です。 docker info、act --version、および gitlab-ci-local --version の設定を確認します。docker info が失敗した場合は、何よりも前にエンジンを始動します。

act を使用してローカルで GitHub Actions を実行します

リポジトリのルート フォルダから act を実行します。最初にジョブをリストし、次に作業中のジョブを実行します。デフォルトでは、act は push イベントをシミュレートするため、他のイベントでのみ実行されるジョブにはイベント名が必要です。

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

最初の実行では、どのランナー イメージを使用するかを尋ねられます。 中 はほとんどのプロジェクトに適しています。小さな画像にはホストされたランナーに含まれるツールが含まれておらず、完全な画像は非常に大きくなります。 「コマンドが見つかりません」というエラーでステップが失敗した場合は、-P ubuntu-latest=<image> でより大きなイメージを選択するか、ステップにツールをインストールしてください。

gitlab-ci-local を使用して GitLab CI をローカルで実行します

gitlab-ci-local は現在のフォルダーから .gitlab-ci.yml を読み取ります。引数を指定しないと、パイプライン全体が実行されます。 1 つのジョブを実行するにはジョブ名を付けます。 --list はジョブを実行せずに表示します。これは、YAML が解析することを簡単に確認する方法です。

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

開始するサンプル ワークフロー

これは、GitTree の GitHub Actions サンプルの形状です。ビルドとテストの 2 つのジョブで、act と GitHub で同じように機能します。コマンドを独自のものに置き換えます。

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

ローカル実行とホストされた CI の違い

• GitHub または GitLab で構成された シークレットと変数は使用できません。仕事に必要なものを渡します。
• 仮想マシンではなくコンテナ: systemd または完全な仮想マシンを必要とするサービスは、同じ方法では実行されません。
• 画像はホストランナーとは異なります。ツールが欠落しているということは、ワークフローが壊れているのではなく、パッケージが欠落しているということです。
• イベントはシミュレートされます: act のデフォルトは push です。再利用可能なワークフロー、インクルード、テンプレートは、エディターではなくランナーによって解決されます。
• 合格したローカル実行はホストされた結果ではありません: ループが短縮されます。あなたのホストにはまだ最終決定権があります。

一般的なエラーと修正

プッシュする前に: 競合を予測し、シークレットを確認し、プッシュをプレビューします。

ローカル パイプラインの実行は、ジョブが通過するかどうかという 1 つの質問に答えます。他の 3 つのチェックは、CI のレポートが遅れているか、まったくレポートされていないかを検出し、それぞれのチェックも何かが送信される前にコンピュータ上で実行されます。

1. マージを予測します。 git merge-tree --write-tree --name-only HEAD origin/main は、作業ツリーに影響を与えることなく、メモリ内でマージし、競合する可能性のあるファイルをリストします。 GitTree は同じ種類のチェックを行い、競合する可能性のあるマージの前に警告します。 Git マージ競合を解決する方法 を参照してください。
2. シークレットを確認します。 コミットまたはプッシュの前に、GitTree は変更をローカルでスキャンして、可能性のあるトークン、パスワード、秘密鍵を探し、見つかった場合はダイアログを表示して停止します。リモートに到達するシークレットは回転する必要があるため、シークレットをキャッチする最も安価な瞬間は、プッシュする前です。警告は保証ではないため、送信した内容を確認してください。
3. プッシュをプレビューします。 出荷プレビューには、プッシュで送信されるコミットとファイルがリストされ、読み取れるワークフロー ファイルごとに、このプッシュでパイプラインが実行される、実行される可能性がある、または実行されないかどうかとその理由が表示されます。

次に、ジョブをローカルで実行し、1 回プッシュします。 秘密の警告ガイド と 出荷プレビュー ガイド では、両方のダイアログについて詳しく説明しています。

Bitbucket Pipelines と Azure Pipelines についてはどうですか?

act または gitlab-ci-local と一致する、bitbucket-pipelines.yml または azure-pipelines.yml に対して維持されているローカル ランナーがありません。実際的なアプローチは、ビルドとテストのコマンドをスクリプト内に保持し、ホストされているパイプラインから呼び出して、ローカル実行専用の小さな GitHub Actions または GitLab CI ファイルを追加することです。 GitTree はこれらのファイルを ローカル ランナーなし としてマークし、まさにこれに対するサンプルを提供します。

次のステップ: パイプラインをローカルで実行するガイド ではすべてのボタンについて説明し、CI/CD の実行 ではホストされた実行、再実行、承認について説明し、ツール ランチャー では GitTree の他の組み込みツールをリストします。