GitHub Actionsのワークフローの基本的な解説

はじめに
- 参考
完成版
- .github/workflows/auto_assign.yml
ワークフローのトリガー
- on
ジョブの定義
- job
ステップの定義
- name
- uses
- with
スクリプトの定義
- script
github.rest.issues.addAssignees メソッド
コンテキストオブジェクト
- context.payload
- context.repo
ワークフローの保存と動作確認
まとめ
おしまい
- コメント

はじめに

GitHub Actionsでは、特定のGitHubイベントがトリガーとなって、ワークフローが実行されます。

本記事では、プルリクエストがオープンされたときに自動的にアサインを行うワークフローをベースに各オプションの解説を行います。

参考

https://tech.yappli.io/entry/github-assign-author

https://tech.youtrust.co.jp/entry/github_actions （寺井さんを見習いたい）

完成版

下記はプルリクエストがオープンされたときにユーザーのアサインを自動的に行うための設定になります。

.github/workflows/auto_assign.yml

name: Auto Assign

on:
  pull_request:
    types: [opened]

jobs:
  add-assignees:
    runs-on: ubuntu-latest

    steps:
      - name: Add Assignee
        uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const { number, user } = context.payload.pull_request;
            await github.rest.issues.addAssignees({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: number,
              assignees: [user.login]
            });

上記のようにymlファイルを適切に配置するだけでGitHub側が設定を読み込んで処理を実行してくれます。毎回Assigneesを自分でポチポチ設定せずに済むようになります！

ワークフローのトリガー

on

on:
  pull_request:
    types: [opened]

on キーではワークフローがどのイベントでトリガーされるかを定義します。

ここではプルリクエストが新しく作成されたときにワークフローがトリガーされます。

今回はプルリクエスト作成時でトリガーするように設定されていますが、いろんなイベントのトリガーがあります。

イベント	説明	設定できるタイプ
push	ブランチにコミットがプッシュされた時にトリガーします。
pull_request	プルリクエストに関連するアクティビティが発生した時にトリガーします。	opened, closed, synchronize など
issue_comment	イシューまたはプルリクエストにコメントが作成された時にトリガーします。	created, edited, deleted
schedule	指定したスケジュールに基づいてトリガーします。
workflow_run	他のワークフローが完了した時にトリガーします。

詳しくは公式のEvents that trigger workflowsを参照してください。

https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows

ジョブの定義

job

jobs:
  add-assignees:
    runs-on: ubuntu-latest

jobs キーでは、ワークフローに含まれるジョブを定義します。

ジョブはワークフロー内で実行される個々のタスクで、ここではアサインを追加するadd-assigneesジョブが定義されています。

runs-on キーは、GitHub Actions ワークフローが実行されるランナー（実行環境）を指定するためのキーです。

ubuntu-latestは、利用可能な最新バージョンのUbuntu仮想環境を使用することを意味します。

基本的にはUbuntuを用いると思います。

ステップの定義

steps:
  - name: Add Assignee
    uses: actions/github-script@v6
    with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
    script: |
      ...略

GitHub Actions ワークフローは、一連のステップ(steps)で構成されます。

ここでは、steps キーでジョブを構成するステップを定義しています。

name

ステップに名前をつけるもので、特にワークフローのログを理解しやすくするために役立ちます。

名前が指定されていないステップでは、実行されるコマンドまたはアクションが名前として利用されます。

uses

特定のアクションを指定するために使用されます。

GitHubが提供しているアクションや、コミュニティが提供しているアクションを指定することができます。

ここではactions/github-script@v6を使用しています。

https://github.com/actions/github-script

with

アクションにパラメータを渡すために使用します。

アクションが要求する入力引数をここで設定できます。

with:
  github-token: ${{ secrets.GITHUB_TOKEN }}

ワークフローではGitHub APIを安全に利用するためにアクセストークンが必要になります。

特に開発者側で発行するものではなく、ワークフロー実行ごとに自動的に新しいトークンが生成されます。

GitHub Actionsで生成されるデフォルトのsecrets.GITHUB_TOKENは、リポジトリへの書き込みアクセスを持っています。

ただし、リポジトリ側にも書き込み許可の設定が必要のため、もし新しいリポジトリなどでワークフローを設定する場合は下記のpermissionsを確認するようにしましょう。

スクリプトの定義

GitHub Script Actionは、GitHub APIにアクセスしたり、ワークフローのデータを操作したりするためのスクリプトをNode.jsの文脈で実行するActionです。

script: |
  const { number, user } = context.payload.pull_request;
  await github.rest.issues.addAssignees({
    owner: context.repo.owner,
    repo: context.repo.repo,
    issue_number: number,
    assignees: [user.login]
  });

script

scriptキーでは実行するJavaScriptコードを定義します。

ここではプルリクエストの作成者をアサインしています。

アクションにどのような引数を渡すべきかは使用するそれぞれのアクションの公式ドキュメントを参照しましょう。

actions/github-script@v6: https://github.com/actions/github-script

github.rest.issues.addAssignees メソッド

githubオブジェクトは、 github-scriptアクションが提供している、GitHub APIと通信を容易にするためのOctokitクライアントインスタンスです。

GitHub Actionsのgithub-scriptアクションを使用してGitHub APIを呼び出す際の構文の一部です。

下記はaddAssigneesに指定するオプションの解説です。

owner / repo

ターゲットとなるリポジトリのオーナー名とリポジトリ名を指定します。

issue_number

アサインを追加したいIssue（またはプルリクエスト）の番号を指定します。

assignees

アサインを追加したいユーザーのログイン名を配列で指定します。

コンテキストオブジェクト

ワークフロー実行時のコンテキスト情報を提供します。

このオブジェクトには、ワークフローが実行されている環境やイベントに関する多くの情報が含まれています。

context.payload

トリガーしたGitHubイベントのペイロードを含んでいます。ここからプルリクエストの情報を抽出します。

  const { number, user } = context.payload.pull_request;

分割代入でaddAssigneesに必要なオブジェクトをcontextから取り出しています。

下記のようにymlのscriptでconsole.log();を出力するとGitHub側のjobsでログを確認することができます。

script: |
  console.log("githubオブジェクト:", github);

contextのオブジェクトは下記のような構成になっていました。

contextオブジェクト: Context {
  payload: {
    action: 'edited',
    changes: { body: [Object] },
    number: 4,
    pull_request: {
      _links: [Object],
      active_lock_reason: null,
      additions: 3,
      assignee: null,
      assignees: [],
      author_association: 'OWNER',
      auto_merge: null,
      base: [Object],
      body: '## 概要\r\n \r\n## 確認方法\r\n',
      changed_files: 1,
      closed_at: null,
      comments: 0,
      comments_url: 'https://api.github.com/repos/ky/github-test/issues/4/comments',
      commits: 3,
      commits_url: 'https://api.github.com/repos/ky/github-test/pulls/4/commits',
      created_at: '2023-10-12T12:28:53Z',
      deletions: 8,
      diff_url: 'https://github.com/ky/github-test/pull/4.diff',
      draft: false,
      head: [Object],
      html_url: 'https://github.com/ky/github-test/pull/4',
      id: 1554049493,
      issue_url: 'https://api.github.com/repos/ky/github-test/issues/4',
      labels: [],
      locked: false,
      maintainer_can_modify: false,
      merge_commit_sha: 'c8bafe85602d5d97c9b6f091064048c845c47c9a',
      mergeable: true,
      mergeable_state: 'clean',
      merged: false,
      merged_at: null,
      merged_by: null,
      milestone: null,
      node_id: 'PR_kwDOKfVOO85coOnV',
      number: 4,
      patch_url: 'https://github.com/ky/github-test/pull/4.patch',
      rebaseable: true,
      requested_reviewers: [],
      requested_teams: [],
      review_comment_url: 'https://api.github.com/repos/ky/github-test/pulls/comments{/number}',
      review_comments: 0,
      review_comments_url: 'https://api.github.com/repos/ky/github-test/pulls/4/comments',
      state: 'open',
      statuses_url: 'https://api.github.com/repos/ky/github-test/statuses/aa8c0abcb9dd9f7fb9fb370872f9f23a97298f29',
      title: 'テスト',
      updated_at: '2023-10-12T12:41:26Z',
      url: 'https://api.github.com/repos/ky/github-test/pulls/4',
      user: [Object]
    },
    repository: {
      allow_forking: true,
      archive_url: 'https://api.github.com/repos/ky/github-test/{archive_format}{/ref}',
      archived: false,
      assignees_url: 'https://api.github.com/repos/ky/github-test/assignees{/user}',
      blobs_url: 'https://api.github.com/repos/ky/github-test/git/blobs{/sha}',
      branches_url: 'https://api.github.com/repos/ky/github-test/branches{/branch}',
      clone_url: 'https://github.com/ky/github-test.git',
      collaborators_url: 'https://api.github.com/repos/ky/github-test/collaborators{/collaborator}',
      comments_url: 'https://api.github.com/repos/ky/github-test/comments{/number}',
      commits_url: 'https://api.github.com/repos/ky/github-test/commits{/sha}',
...
      web_commit_signoff_required: false
    },
    sender: {
      avatar_url: 'https://avatars.githubusercontent.com/u/78721963?v=4',
      events_url: 'https://api.github.com/users/ky/events{/privacy}',
      followers_url: 'https://api.github.com/users/ky/followers',
      following_url: 'https://api.github.com/users/ky/following{/other_user}',
...
      url: 'https://api.github.com/users/ky'
    }
  },
  eventName: 'pull_request',
  sha: 'c8bafe85602d5d97c9b6f091064048c845c47c9a',
  ref: 'refs/pull/4/merge',
  workflow: 'Auto Assign',
  action: '__actions_github-script',
  actor: 'ky',
  job: 'add-assignees',
  runNumber: 5,
  runId: 6495775002,
  apiUrl: 'https://api.github.com',
  serverUrl: 'https://github.com',
  graphqlUrl: 'https://api.github.com/graphql'
}

context.repo

レポジトリの情報（オーナー名とレポジトリ名）を含んでいます。

ワークフローの保存と動作確認

このワークフローを.github/workflowsディレクトリに保存してGitHub リポジトリにプッシュすると、GitHub Actionsがこのワークフローを検出し、定義されたイベント（ここではプルリクエストのオープン）で自動的にジョブが実行されるようになります。

on:
  pull_request:
    types: [opened]

まとめ

GitHub ActionsとGitHub Script Actionを使用することで、GitHub上での開発フローを自動化し、効率化を図ることが可能です。

本記事では、プルリクエストがオープンされた際に自動的にオープナーをアサインするワークフローの設定や詳細について解説しました。

GitHub Actionsはイベントに応じて自動的な動作を設定可能

ワークフローはイベントトリガー、ジョブ、ステップで構成されている

一例として**`github-script`**アクションでAPI利用してユーザーアサインを自動化出来ることができる

おしまい

本記事の内容は以上になります！開発プロセスの自動化はどのプロジェクトにおいても重要だと思います。チームでの開発が円滑に進められるようにさらに知見を深めていきたいと思います。

プログラミングスクールのご紹介 (卒業生より)

お世話になったプログラミングスクールであるRUNTEQです♪

https://runteq.jp/r/ohtFwbjW

こちらのリンクを経由すると１万円引きになります。

RUNTEQを通じて開発学習の末、受託開発企業をご紹介いただき、現在も双方とご縁があります。

もし、興味がありましたらお気軽にコメントか、TwitterのDMでお声掛けください。

https://twitter.com/outputky

Yanonoblog!

こつこつと