ノート: GitHub Actionsは現在GitHub AEでベータです。
概要
ワークフローで使用するアクションは、以下の場所で定義できます。
- パブリック リポジトリ
- ワークフローファイルがアクションを参照するのと同じリポジトリ
- Docker Hubで公開された Docker コンテナイメージ
GitHub Marketplaceは、GitHubコミュニティによって構築されたアクションを見つけるための中央となる場所です。 GitHub Marketplace ページでは、アクションをカテゴリでフィルタできます。
ワークフローエディタで Marketplace アクションを参照する
リポジトリのワークフローエディタで、直接アクションを検索し、ブラウズできます。 サイドバーから特定のアクションを検索し、注目のアクションを見て、注目のカテゴリをブラウズできます。 また、アクションがGitHubコミュニティから受けたStarの数も見ることができます。
- リポジトリで、編集したいワークフローファイルにアクセスします。
- ファイルビューの右上隅の をクリックしてワークフローエディタを開きます。
- エディタの右側でGitHub Marketplaceサイドバーを使ってアクションをブラウズしてください。 バッジの付いたアクションは、GitHub がアクションの作者をパートナー Organization として確認したことを示します。
ワークフローにアクションを追加する
アクションのリストのページには、アクションのバージョンと、そのアクションを利用するために必要なワークフローの構文が含まれています。 アクションが更新された場合でもワークフローを安定させるために、ワークフローファイルで Git または Docker タグ番号を指定することにより、使用するアクションのバージョンを参照できます。
- ワークフローで使いたいアクションにアクセスしてください。
- "Installation（インストール）"の下で、をクリックしてワークフローの構文をコピーしてください。
- この構文をワークフロー中に新しいステップとして貼り付けてください。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。
- アクションで入力が必要な場合は、ワークフローで設定します。 アクションに必要な入力については、「アクションで入力と出力を使用する」を参照してください。
カスタムアクションにリリース管理を使用する
コミュニティアクションの作者は、タグ、ブランチ、または SHA 値を使用してアクションのリリースを管理するオプションがあります。 他の依存関係と同様に、アクションの更新を自動的に受け入れる際のお好みに応じて、使用するアクションのバージョンを指定する必要があります。
ワークフローファイルでアクションのバージョンを指定します。 リリース管理へのアプローチに関する情報、および使用するタグ、ブランチ、または SHA 値を確認するには、アクションのドキュメントを確認してください。
タグの使用
タグは、メジャーバージョンとマイナーバージョンの切り替えタイミングを決定するときに役立ちますが、これらはより一過性のものであり、メンテナから移動または削除される可能性があります。 この例では、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 と呼ばれる必須の入力を定義し、何も指定されていない場合に使用されるデフォルト値を含みます。 output キーワードは、結果の場所を示す 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 AE に含まれているアクションを使用する
デフォルト設定では、
GitHub AE で公式の GitHub 作者のアクションのほとんどを使用できます。 詳しい情報については、「GitHub AE でアクションを使用する」を参照してください。
ワークフロー ファイルでアクションを使用するのと同じリポジトリ内のアクションの参照
ワークフロー ファイルがアクションを使用するのと同じリポジトリでアクションが定義されている場合、そのアクションはワークフロー ファイル内の{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:
# このステップは、リポジトリのコピーをチェックアウトします。
- uses: actions/checkout@v2
# このステップは、アクションを含むディレクトリを参照します。
- uses: ./.github/actions/hello-world-action
action.yml ファイルは、アクションのメタデータを提供するために使用されます。 このファイルの内容については、「GitHub Actions のメタデータ構文」をご覧ください。
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 コンテナのアクションを作成する」を参照してください。
次のステップ
GitHub Actions の詳細については、「GitHub Actions の重要な機能」を参照してください。