ワークフローで事前に作成されたビルディング ブロックを使用する

あらかじめ記述されたアクションを使用およびカスタマイズして、ワークフローを強化できます。

この記事で

GitHub で GHE.com にアクセスする場合、GitHub.com へのハードコーディングされた API 呼び出しを含むアクションが期待どおりに機能しない可能性があることに注意してください。

ワークフローエディタで Marketplace アクションを参照する

リポジトリのワークフローエディタで、直接アクションを検索し、ブラウズできます。 サイドバーから特定のアクションを検索し、注目のアクションを見て、注目のカテゴリをブラウズできます。 また、 GitHub コミュニティからアクションが受け取った星の数を表示することもできます。

  1. リポジトリで、編集したいワークフローファイルにアクセスします。
  2. ファイル ビューの右上隅にあるワークフロー エディターを開くには、[ ] をクリックします。

ヘッダー セクションを示すワークフロー ファイルのスクリーンショット。 ファイル編集用の鉛筆アイコンが濃いオレンジ色の輪郭で強調表示されています。

  1. エディターの右側にある GitHub Marketplace サイドバーを使用してアクションを参照します。 バッジを持つアクションは、GitHubがパートナー組織としてアクションの作成者を検証したことを示します。

ファイル エディターでのワークフローのスクリーンショット。 サイドバーには、Marketplace のアクションが表示されています。 "GitHub によって認証されたクリエイター" バッジのアウトラインはオレンジ色です。

ワークフローにアクションを追加する

ワークフロー ファイル内のアクションを参照することで、ワークフローにアクションを追加できます。 ワークフローで使用するアクションは、以下の場所で定義できます。

  • ワークフロー ファイルと同じリポジトリ
  • ワークフローへのアクセスを許可するように構成されている同じエンタープライズ アカウント内の内部リポジトリ
  • すべてのパブリック リポジトリ
  • Docker Hubに公開されたDockerコンテナイメージ

GitHub Actions ワークフローで参照されているアクションは、ワークフローを含むリポジトリの依存関係グラフで依存関係として表示できます。 詳しくは、「依存関係グラフ」をご覧ください。

メモ

セキュリティを強化するため、GitHub Actions はアクションまたは再利用可能なワークフローのリダイレクトをサポートしません。 つまり、所有者、アクションのリポジトリの名前、またはアクションの名前が変更されると、そのアクションを以前の名前で使用するすべてのワークフローは失敗します。

GitHub Marketplace からアクションを追加

アクションのリストのページには、アクションのバージョンと、そのアクションを利用するために必要なワークフローの構文が含まれています。 アクションが更新された場合でもワークフローを安定させるために、ワークフローファイルで Git または Docker タグ番号を指定することにより、使用するアクションのバージョンを参照できます。

  1. ワークフローで使いたいアクションにアクセスしてください。
  2. クリックすると、マーケットプレースに登録されているそのアクションの完全な情報を参照できます。
  3. [インストール] で、 をクリックしてワークフロー構文をコピーします。

マーケットプレースに登録されているそのアクションの完全な情報のスクリーンショット。 そのアクションの [クリップボードにコピー] アイコンが濃いオレンジ色の輪郭で強調表示されています。

  1. この構文をワークフロー中に新しいステップとして貼り付けてください。 詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。
  2. アクションで入力が必要な場合は、ワークフローで設定します。 アクションで必要な可能性がある入力については、「ワークフローで事前に作成されたビルディング ブロックを使用する」をご覧ください。

また、ワークフローに追加するアクションの Dependabot version updates を有効にすることもできます。 詳しくは、「Dependabot でアクションを最新に保つ」をご覧ください。

同じリポジトリからのアクションの追加

ワークフロー ファイルがアクションを使用するのと同じリポジトリでアクションが定義されている場合、そのアクションはワークフロー ファイル内の {owner}/{repo}@{ref} または ./path/to/dir 構文を使用して参照できます。

リポジトリ ファイル構造の例:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

パスはデフォルトの作業ディレクトリ (github.workspace、$GITHUB_WORKSPACE) に対する相対パス (./) です。 アクションがワークフローとは異なる場所にリポジトリをチェックアウトする場合は、ローカル アクションに使用される相対パスを更新する必要があります。

ワークフロー ファイルの例:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v6
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

この action.yml ファイルは、アクションのメタデータを提供するために使用されます。 このファイルの内容については、「メタデータ構文リファレンス」をご覧ください。

別のリポジトリからのアクションの追加

アクションがワークフロー ファイルとは異なるリポジトリで定義されている場合は、ワークフロー ファイル内で {owner}/{repo}@{ref} 構文を使用してアクションを参照できます。

アクションは、パブリック リポジトリ またはワークフローへのアクセスを許可するように構成された内部リポジトリに格納する必要があります。 詳細については、「 アクションとワークフローを企業と共有する.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

GHE.com 上のアクションへのアクセスを有効にしている場合は、この構文を使用して、自分のエンタープライズ内またはGitHub.com上のアクションを参照できます。 GitHub Actions は、最初に企業でアクションを検索してから、 GitHub.comにフォールバックします。

Docker Hubでのコンテナーの参照

Docker Hubの発行済み Docker コンテナー イメージでアクションが定義されている場合は、ワークフロー ファイルで docker://{image}:{tag} 構文を使用してアクションを参照する必要があります。 コードとデータを保護するには、ワークフローで使用する前に、Docker コンテナー イメージの整合性をDocker Hubから確認することを強くお勧めします。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Docker アクションの例については、Docker-image.yml ワークフローと「Docker コンテナーのアクションを作成する」をご覧ください。

ワークフローでアクションを使用するためのセキュリティ強化

GitHub には、ワークフローのセキュリティを強化するために使用できるセキュリティ機能が用意されています。 GitHubの組み込み機能を使用して、使用するアクションの脆弱性に関する通知を受け取ったり、ワークフロー内のアクションを最新の状態に保つプロセスを自動化したりできます。 詳しくは、「セキュリティで保護された使用に関するリファレンス」をご覧ください。

カスタムアクションにリリース管理を使用する

コミュニティアクションの作者は、タグ、ブランチ、または SHA 値を使用してアクションのリリースを管理するオプションがあります。 他の依存関係と同様に、アクションの更新を自動的に受け入れる際のお好みに応じて、使用するアクションのバージョンを指定する必要があります。

ワークフローファイルでアクションのバージョンを指定します。 リリース管理へのアプローチに関する情報、および使用するタグ、ブランチ、または SHA 値を確認するには、アクションのドキュメントを確認してください。

メモ

サードパーティのアクションを使用する場合は、SHA 値を使用することをお勧めします。 ただし、Dependabot が Dependabot alerts を作成するのは、セマンティック バージョニングを使用する脆弱な GitHub Actions に対してのみである点に注意が必要です。 詳細については、「セキュリティで保護された使用に関するリファレンス」および「Dependabot アラート」を参照してください。

タグの使用

タグは、メジャーバージョンとマイナーバージョンの切り替えタイミングを決定するときに役立ちますが、これらはより一過性のものであり、メンテナから移動または削除される可能性があります。 この例では、v1.0.1 としてタグ付けされたアクションをターゲットにする方法を示しています。

steps:
  - uses: actions/javascript-action@v1.0.1

SHA の使用

より信頼性の高いバージョン管理が必要な場合は、アクションのバージョンに関連付けられた SHA 値を使用する必要があります。 SHA は不変であるため、タグやブランチよりも信頼性が高くなります。 ただし、このアプローチは、重要なバグ修正やセキュリティ更新プログラムなどのアクションの更新を自動的に受信しないことを意味します。 短縮された値ではなく、コミットの完全な SHA 値を使う必要があります。 SHA を選択するときは、アクションのリポジトリからであり、リポジトリ フォークではないことを確認してください。 この例では、アクションの SHA を対象とします。

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

ブランチの使用

アクションのターゲットブランチを指定すると、そのブランチに現在あるバージョンが常に実行されます。 ブランチの更新に重大な変更が含まれている場合、このアプローチは問題を引き起こす可能性があります。 この例では、@main という名前のブランチを対象とします。

steps:
  - uses: actions/javascript-action@main

詳しくは、「カスタム アクションについて」をご覧ください。

アクションで入力と出力を使用する

多くの場合、アクションは入力を受け入れたり要求したりして、使用できる出力を生成します。 たとえば、アクションでは、ファイルへのパス、ラベルの名前、またはアクション処理の一部として使用するその他のデータを指定する必要がある場合があります。

アクションの入力と出力を確認するには、リポジトリのルート ディレクトリの action.yml を確認します。

この action.yml の例では、inputs キーワードによって file-path という名前の必須の入力が定義され、何も指定されていない場合に使用される既定値が含まれています。 outputs キーワードは、結果を配置する場所を示す results-file という名前の出力を定義します。

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"