Skip to main content

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

アクションは、ワークフローを動かす構成要素です。 ワークフローには、コミュニティによって作成されたアクションを含めることも、アプリケーションのリポジトリ内に直接独自のアクションを作成することもできます。 このガイドでは、アクションを発見、使用、およびカスタマイズする方法を説明します。

概要

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

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

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

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

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

  1. リポジトリで、編集したいワークフローファイルにアクセスします。
  2. ファイル ビューの右上隅の をクリックして、ワークフロー エディターを開きます。 ヘッダー セクションを示すワークフロー ファイルのスクリーンショット。 ファイル編集用の鉛筆アイコンが濃いオレンジ色の輪郭で強調表示されています。
  3. エディタの右側でGitHub Marketplaceサイドバーを使ってアクションをブラウズしてください。 バッジの付いたアクションは、GitHub がそのアクションの作者をパートナー組織として認証したことを示します。 編集モードのワークフロー ファイルのスクリーンショット。 右側のサイドバーには、Marketplace のアクションが表示されています。 作成者が GitHub によって認証されていることを示すスタンプ アイコンのチェックマークが、オレンジ色で囲まれています。

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

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

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

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

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

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

  1. ワークフローで使いたいアクションにアクセスしてください。
  2. クリックすると、マーケットプレースに登録されているそのアクションの完全な情報を参照できます。
  3. [インストール] の下で、 をクリックしてワークフローの構文をコピーします。 マーケットプレースに登録されているそのアクションの完全な情報のスクリーンショット。 そのアクションの [クリップボードにコピー] アイコンが濃いオレンジ色の輪郭で強調表示されています。
  4. この構文をワークフロー中に新しいステップとして貼り付けてください。 詳しくは、「ギットハブ アクション のワークフロー構文」を参照してください。
  5. アクションで入力が必要な場合は、ワークフローで設定します。 アクションで必要な可能性がある入力について詳しくは、「アクションの検索とカスタマイズ」をご覧ください。

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

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

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

Example repository file structure:

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

The path is relative (./) to the default working directory (github.workspace, $GITHUB_WORKSPACE). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated.

Example workflow file:

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@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-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 値を使用することをお勧めします。 ただし、Dependabot では、セマンティック バージョン管理を使用する脆弱な GitHub Actions に対してのみ 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.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 の重要な機能」をご覧ください。