アクションの検索とカスタマイズ

概要

ワークフローで使用するアクションは、以下の場所で定義できます。

ワークフローファイルと同じリポジトリ
すべてのパブリックリポジトリ
Docker Hubで公開された Docker コンテナイメージ

GitHub Marketplace は、GitHub コミュニティによって作成されたアクションを検索するための一元的な場所です。 GitHub Marketplace ページを使用すると、カテゴリ別にアクションをフィルター処理できます。

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

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

リポジトリで、編集したいワークフローファイルにアクセスします。
ファイルビューの右上隅のをクリックして、ワークフローエディターを開きます。
エディタの右側でGitHub Marketplaceサイドバーを使ってアクションをブラウズしてください。バッジの付いたアクションは、GitHub がアクションの作者をパートナー Organization として確認したことを示します。

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

ワークフローファイル内のアクションを参照することで、ワークフローにアクションを追加できます。

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

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

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

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

ワークフローで使いたいアクションにアクセスしてください。
Installation の下で、をクリックしてワークフローの構文をコピーします。
この構文をワークフロー中に新しいステップとして貼り付けてください。詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。
アクションで入力が必要な場合は、ワークフローで設定します。アクションに必要な入力の詳細については、「アクションでの入力と出力の使用」を参照してください。

ワークフローに追加したアクションに対して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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - uses: actions/checkout@v3
      # This step references the directory that contains the action.
      - uses: ./.github/actions/hello-world-action

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

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

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

アクションはパブリックリポジトリに格納する必要があります。

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

Docker Hubでのコンテナの参照

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

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

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

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

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

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

注: サードパーティのアクションを使用する場合は、SHA 値を使用することをお勧めします。詳細については、「GitHub Actions のセキュリティ強化」を参照してください。

タグの使用

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

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

SHA の使用

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

steps:
  - uses: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

ブランチの使用

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

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

詳細については、「アクションにリリース管理を使用する」を参照してください。

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

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

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

この 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"

次の手順

GitHub Actions について引き続き学習するには、「GitHub Actions の重要な機能」を参照してください。