GitHub Actions

GitHub Actions は GitHub に組み込まれた自動化プラットフォームで、コードリポジトリ内で自動化フローを直接定義・実行できます。外部の CI/CD ツールは不要です。

一般的な用途としては、コードプッシュ後の自動テスト実行、PR マージ後のサーバーへの自動デプロイ、定期的なデータ取得スクリプトの実行などがあります。

GitHub Actions は公開リポジトリであれば完全無料、プライベートリポジトリには毎月 2,000 分の無料枠があります。

中核となる概念

設定ファイルを書き始める前に、まず以下のいくつかの中核概念を理解する必要があります。それらの関係は次のとおりです：

仓库（Repository）
└── Workflow（工作流）          ← 一个 .yml 文件 = 一个 Workflow
    ├── Event（触发事件）        ← 什么情况下启动这个 Workflow，如 push、PR
    └── Job（作业）× N          ← 一个 Workflow 可以包含多个并行或串行的 Job
        ├── Runner（运行器）     ← 执行 Job 的服务器，如 ubuntu-latest
        └── Step（步骤）× N     ← Job 内按顺序执行的一系列操作
            ├── Action          ← 可复用的封装好的操作，如 actions/checkout
            └── Run             ← 直接执行 Shell 命令

最初の Workflow を作成する

1、ディレクトリ構造

すべての Workflow ファイルは、リポジトリのルートディレクトリの.github/workflows/フォルダー配下に置く必要があります。ファイル名は.yml 或 .yamlで終わります。ファイル名は自由に設定できます：

your-repo/
├── .github/
│   └── workflows/
│       ├── ci.yml          ← 持续集成流程（如运行测试）
│       ├── deploy.yml      ← 部署流程
│       └── scheduled.yml   ← 定时任务
├── src/
├── package.json
└── README.md

1 つのリポジトリには複数の Workflow ファイルを置くことができます。それらは互いに独立しており、それぞれで定義されたイベントによってトリガーされます。

2、最もシンプルな Workflow

以下は最も基本的な例です。リポジトリにコードをプッシュするたびに「Hello, GitHub Actions!」の 1 行を出力します：

YAML ファイルはインデントに非常に敏感で、スペースでのインデントが必要で、Tab キーは使えません。VS Code を使用して YAML プラグインをインストールすると、リアルタイムでフォーマットエラーを検出できるのでおすすめです。

トリガーイベント（on）

onフィールドは、どのイベントがこの Workflow をトリガーするかを定義します。単一のイベントでも、複数のイベントの組み合わせでもかまいません。

1、よく使うトリガーイベント

2、ブランチ・パスのフィルタリング

3、スケジュールトリガー（schedule）

標準の Cron 式を使用して実行時刻を定義します。タイムゾーンは UTC です（北京時間 = UTC+8 のため換算が必要です）：

4、手動トリガー（workflow_dispatch）

workflow_dispatchGitHub Webページの Actions タブで手動でボタンをクリックして Workflow を起動でき、入力パラメータも定義できます：

Jobs と Steps の詳細解説

1、Job の基本構造

2、実行環境（runs-on）

GitHub は以下の無料のホストランナーを提供しており、必要に応じて選択できます：

3、Job 間の依存関係（needs）

デフォルトでは、複数の Job は並列実行されます。次を使用するとneedsJob の実行順序を設定し、直列の依存関係を形成できます：

4、条件実行（if）

次を使用するとifJob や Step を実行するかどうかを制御できます。ブランチの判別や前のステップの成功判定などによく使われます：

環境変数と Secrets

1、環境変数（env）

環境変数は Workflow の3つのレベルで定義でき、影響範囲は順に狭くなります：

2、GitHub 組み込み変数（github コンテキスト）

GitHub Actions には組み込みのコンテキスト変数が用意されており、任意の場所で${{ }}構文で参照できます：

3、Secrets（機密情報の管理）

パスワード、API キー、サーバーアドレスなどの機密情報はyml ファイルに直接記述できません（コードは公開されているため）、GitHub リポジトリの Secrets に保存する必要があります。

設定手順：リポジトリページに移動 →Settings → Secrets and variables → Actions→ クリックNew repository secret、名前と値を入力して保存します。

よく使う Actions の紹介

GitHub 公式およびコミュニティは、すぐに使える Action を数多く提供しており、uses: action名称@版本これらを参照することで、よくある操作を重複して記述するのを避けられます。

1、actions/checkout（コードの取得）

ほぼすべての Workflow の最初のステップはリポジトリのコードを取得することです。公式のアクションを使用します。actions/checkout：

2、actions/setup-node（Node.js 環境のセットアップ）

3、actions/setup-python（Python 環境のセットアップ）

4、actions/cache（依存関係のキャッシュによるビルド高速化）

Workflow を実行するたびに依存関係をダウンロードし直すと遅くなります。cache Action を使用すると依存関係をキャッシュでき、次回の実行時にキャッシュを直接使用できるため、ビルド時間を大幅に短縮できます：

5、actions/upload-artifact / download-artifact（Job 間でのファイル受け渡し）

異なる Job は独立した仮想マシンで実行されるため、ファイルを直接共有できません。artifact（成果物）を介して、ある Job の出力ファイルを別の Job に渡すことができます：

マトリックスビルド（Matrix）

マトリックスビルドを使うと、1つの Job 設定で複数の環境で並行実行できます。バージョン横断や OS 横断の互換性テストによく使用されます：

実践例

例1：Node.js プロジェクト CI（自動テスト）

コードをプッシュするか PR を作成するたびに、依存関係のインストール、コードチェック、テストを自動実行します：

例2：Python プロジェクト CI

例3：Docker イメージのビルドとプッシュ

例4：ビルド後のサーバーへの自動デプロイ

例5：スケジュールタスク（データベースの自動バックアップ）

デバッグのコツ

1、Debug ログを有効にする

Workflow の実行が失敗してもログ情報が不十分な場合、詳細デバッグモードを有効にできます。方法：リポジトリに入りSettings → Secrets and variables → Actions、以下の2つの Secret を追加します（値はすべてtrue）：

• ACTIONS_RUNNER_DEBUG：ランナーの詳細ログを有効にする
• ACTIONS_STEP_DEBUG：各 Step の詳細デバッグログを有効にする

2、コンテキスト情報を出力して調査を支援する

3、Workflow のローカルテスト（act を使用）

コードをプッシュするたびにしか Workflow をテストできないのは効率が非常に低い。actこれはオープンソースツールであり、GitHub Actions をローカルでシミュレーション実行でき、デバッグ効率を大幅に向上させます：

# 安装 act（需要本地已安装 Docker）
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 在仓库根目录运行所有 Workflow
act

# 只运行指定事件触发的 Workflow
act push

# 只运行指定的 Job
act -j build

ローカルでテストする際は、actDocker コンテナを使用して GitHub の実行環境をシミュレートしますが、一部の Action（例：actions/cache）はローカルのシミュレーションでは実際の環境と効果が異なる場合があります。最終結果は GitHub 上での実際の動作を基準とします。

よくある質問と注意点

1、権限の問題（Permission denied）

Workflow がリポジトリへのコードのプッシュや Issues の操作を必要とする場合は、設定ファイルで権限を明示的に宣言する必要があります：

2、Workflow の循環トリガーの回避

Workflow がリポジトリに自動的にコードをプッシュすると、新しい push イベントがトリガーされ、無限ループが発生する可能性があります。解決方法：自動コミットの commit message に[skip ci]キーワードを追加すると、GitHub はそのコミットの Workflow トリガーをスキップします：

git commit -m "自动格式化代码 [skip ci]"

3、YAML 特殊文字のエスケープ

にrunフィールドの Shell コマンドで${{ }}式を使用する場合、式にコロン（:）などの YAML 特殊文字が含まれる場合は、値全体を引用符で囲むか、環境変数に代入してから使用する必要があります：

完全なドキュメントは公式ドキュメントを参照してください：https://docs.github.com/zh/actions