ワークフローを読む・書く — YAMLとビルド成果物（アーティファクト）
📖 このページのゴール：小さな YAML を「1行ずつ」読み解いて、ワークフロー（＝自動でやる作業の手順書）の形をつかみます。さらに、ビルドした成果物（アーティファクト）を保存する書き方と、「キャッシュとは別物」という勘どころまで。読み終わると、自分で短いワークフローが書けます。 ← 目次・はじめにへもどる
前のページで、GitHub Actions は on（いつ）→ jobs（やること）→ steps（1手順ずつ） の形だと見ました。ここではその中身を、実際の YAML（ヤムル＝設定を書くテキスト形式）で1行ずつ見ていきます。むずかしくありません。英語の単語が、そのまま意味になっているだけです。
ファイルの置き場所は決まっていて、リポジトリの中の .github/workflows/ フォルダに置きます。ファイル名は自由（例：ci.yml）。このフォルダに YAML を置くと、GitHub が自動で見つけて実行してくれます。
1. いちばん小さな「テストするワークフロー」🟢
まずは「push したら、テストを走らせる」だけの最小例です。短いので、こわがらずに。
name: CI
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm test
1行ずつ読むと：
| 行 | 書いてあること | やさしく言うと |
|—|—|—|
| name: CI | このワークフローの名前 | 画面に出る見出し（なくてもOK） |
| on: [push] | きっかけ＝トリガー | 「push されたら動かす」 |
| jobs: | やることの一覧 | この下に仕事（ジョブ）を並べる |
| test: | ジョブの名前 | test という名前の仕事をひとつ作る |
| runs-on: ubuntu-latest | 動かす場所＝ランナー | GitHub が貸す使い捨ての Linux パソコンの上で動かす |
| steps: | 手順の並び | この下に1手順ずつ書く |
| - uses: actions/checkout@v4 | 既製の部品を使う（uses） | 自分のソースコードを取ってくる部品（これが無いと中身が空） |
| - uses: actions/setup-node@v4 | 同じく既製の部品 | Node.js を用意する部品 |
| ` with: / node-version: 20 | 部品への**設定**（with） | 「Node は**20番**を使ってね」と渡す |
| - run: npm ci | **コマンドを実行**する（run） | **必要なライブラリを入れる**（npm install の確実版） |
| - run: npm test` | 同じくコマンド実行 | テストを走らせる。失敗すれば、この回は赤（失敗）になる |
ポイントは、キーの意味を覚えれば読めるということ。表にまとめると：
| キー | 意味 | ひとことで |
|---|---|---|
on |
トリガー | いつ動かす？（push / PR / 定期 / 手動 …） |
jobs |
ジョブの集まり | やることの入れ物。複数あれば並行で動く |
runs-on |
ランナー指定 | どのパソコンで動かす？（例：ubuntu-latest） |
steps |
手順の並び | ジョブの中の1手順ずつ。上から順に実行 |
uses |
アクションを使う | 既製の部品（レゴ）を呼ぶ。@v4 はバージョン |
run |
コマンド実行 | シェルのコマンドをそのまま動かす |
with |
部品への入力 | uses の部品に渡す設定（例：Nodeの番号） |
🔧 actions/checkout@v4 の @v4 のように、部品にはバージョンを付けるのがふつうです（付けないと意味が変わったときに困る）。バージョン固定の話はシークレットと安全でもう少し触れます。
2. ビルドして「成果物（アーティファクト）」を残す🟢
テストが通ったら、次はビルド（＝配れる形に組み立てること）して、その出来上がりを保存してみましょう。この「出来上がり」を アーティファクト（artifact＝成果物） と呼びます。
先ほどの steps: の最後に、2手順を足すイメージです。
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/
1行ずつ読むと：
| 行 | 書いてあること | やさしく言うと |
|—|—|—|
| - run: npm run build | ビルドのコマンド | 配れる形に組み立てる（多くは dist/ フォルダに出る） |
| - uses: actions/upload-artifact@v4 | 成果物を保存する部品 | 出来上がりをGitHub に預けて、あとでダウンロードできるようにする |
| ` with: | 部品への設定 | 下の2つを渡す |
| name: build-output | 保存名 | この成果物の**ラベル名**（自由に付ける） |
| path: dist/ | 保存する場所 | **どのフォルダ／ファイルを残すか**（ここでは dist/` フォルダ） |
これで、ワークフローの実行ページから build-output をダウンロードできます。テストの結果レポートやカバレッジ（どれだけテストが通ったかの記録）も、同じ upload-artifact で保存・受け渡しできます。
| 何を残せる？ | 例 |
|---|---|
| ビルド済みアプリ | dist/ フォルダ、実行ファイル |
| テストレポート | テスト結果の HTML／XML |
| カバレッジ | どこまでテストされたかの記録 |
3. 「アーティファクト」と「キャッシュ」は別物🟢
名前が似ていて混同しがちですが、目的がまるで違います。
| アーティファクト（成果物） | キャッシュ（一時保存） | |
|---|---|---|
| 何のため？ | 成果物を残す・配る | 次回を速くする |
| 中身の例 | ビルド済みアプリ、テストレポート | node_modules などの依存ライブラリ |
| あなたが見る？ | 見る・ダウンロードするもの | ふつう裏方で気にしない |
| 部品 | actions/upload-artifact |
actions/cache |
ひとことで言うと——アーティファクト＝「結果を残したい」、キャッシュ＝「毎回ダウンロードし直すのが遅いから取っておく」。キャッシュで速くする話は速く・安くでくわしく見ます。
4. まずは「push でテストだけ」から、小さく始める🟢
ここまで盛りだくさんでしたが、最初から全部やる必要はありません。
いちばん小さい一歩は、セクション1の「push でテストするだけ」。これを置くだけで、コードを上げるたびに自動でテストが走り、壊れていれば赤で教えてくれます。慣れてきたら、ビルド → 成果物の保存 → デプロイ…と少しずつ足していけばOKです。
🔧 一度にビルドもデプロイも通知も…と詰め込むと、どこで失敗したか分かりにくくなります。まず1つ動かして、緑（成功）を見てから次を足すのが、結局いちばん速い近道です。
🟢 ひとことで言うと
ワークフローは on→jobs→steps の形で、キーの意味（uses＝部品を使う／run＝コマンド実行／with＝設定）が分かれば読めます・書けます。ビルドした成果物は upload-artifact でアーティファクト（成果物）として保存でき、これは速くするための「キャッシュ」とは別物。最初は 「push でテストだけ」 から小さく始めましょう。
➡️ 次へ
次のページ：実例カタログ — 何ができる？（テスト・CodeQL・レビューBot・デプロイ・リリース…） → ← 目次・はじめにへもどる