🗂

GitHubActionsを使ったパイプライン構築事始め

2024/08/22に公開

GitHub Actions

CI/CD

tech

はじめに

こんにちは！　IT企業でエンジニアをしている和泉と申します。
普段は、Pythonを使ったアプリケーションの開発などに携わっています。
今回は、GitHubActionsを利用したCICDパイプラインの構築のご紹介をしたいと思います。

今回の記事の対象者

今回の記事の対象者は、以下のような方を対象にしています。

何かしらのアプリケーションを開発していて、デプロイを手動で行っている方
デプロイを自動化したい方
BashなどのLinuxコマンドを実行したことがある方
GitおよびGitHubを利用したことがある方
AWSを少し触ったことがある方

IT初心者やLinuxコマンドを実行したことがない方には、非常に難しい内容になると思いますので、ご了承ください。

GitHubActionsとは？

公式ドキュメントには、以下の通り記載されております。

GitHub Actions は、ビルド、テスト、デプロイのパイプラインを自動化できる
継続的インテグレーションと継続的デリバリー (CI/CD) のプラットフォームです。

簡単にいうと、GitHubにソースコードをアップロードすると、自動的にデプロイまで行ってくれる仕組みを提供しているサービスだと考えております。
これにより、プロジェクトに参加しているメンバー全員が、気軽にデプロイができるようになります。

GitHubActionsを利用するために知っておきたい用語

ワークフロー
- ワークフローとは、GitHubActionsで実行する一連の自動化処理のことを示します。
- リポジトリに対して、特定のイベント(例: push、fork)が起こった際に実行されます。
ジョブ
- ジョブとは、ワークフロー内の、実行される一連のタスクの集まりです。
- 複数のジョブが存在する場合に、連携をさせることも可能です。
ステップ
- ステップとは、ジョブの中で実行されるタスクのことです。
- 一つのジョブの中に、1つ以上のステップが存在しており、順次実行されます。
- また、ステップでは、コマンドの実行や特定のアクションを実行します。
アクション
- ステップ内で再利用できるように、共通化されたタスクです。
  - 例1: ユニットテストを実行するNode.jsをセットアップする。
  - 例2: awsへの認証を行う。
- アクションは、GitHubやAWSなどが公式で提供している物もありますが、ユーザー自身で作成することも可能です。
ランナー
- ステップを実行するための環境です。
- 一般的には、公式で準備している環境を使うことが多いと思いますが、ユーザー自身で作成することも可能です。
  - 公式で準備しているランナーの一覧は、こちらです。
  - ユーザー自身で、新しくランナーを構築する場合は、こちらを参照して下さい。
イベント
- ワークフローを実行するためのトリガーになる出来事です。(イベントの種類は、こちらを参照して下さい。)
  - 例えば、mainブランチにpushされたら、ワークフローを実行する。

GitHubActionsを利用するための、ディレクトリ構成

以下にサンプルプログラムのディレクトリ構成を示します。
ここで、重要なことは、リポジトリのルートディレクトリに、.github/workflowsディレクトリが存在することです。
GitHubActionsは、.github/workflows内にYamlファイルを配置することで、実行できます。

.
├── .git
├── .github
│   └── workflows
│       └── github-actions-sample.yml
├── .gitignore
├── Dockerfile
├── LICENSE
├── README.md
├── requirements.txt
├── src
│   ├── calc.py
│   └── main.py
└── tests
    └── test_calc.py

GitHubAction用のYamlファイルの書き方

ファイルの書き方を記載する前に(前提)

今回、ワークフローの概要は以下です。

自動テストの実行
AWSのECRというサービスに、コンテナイメージをデプロイする。
※ AWSのデプロイは、OIDC（OpenID Connect）を利用します。OIDCは、GitHubActionsから外部のサービス(今回はAWS)に安全に接続する方法になります。
※ OIDCを利用するためには、AWSアカウントの作成とOIDC用の設定が必要になります。
※ AWSでのOIDCの設定方法は、こちらをご確認して下さい。

サンプルコード

今回利用するサンプルコードは、こちらにあります。

name: github-actions-sample # ワークフローの名前
# イベントトリガーの設定
on:
  push: # pushした際の設定
    branches: # ブランチの指定
      - main

# ジョブの設定
jobs:
  tests: # 自動テストのジョブ
    runs-on: ubuntu-latest # 実行環境(ランナー)の指定
    env: # 環境変数の設定
      PYTHONPATH: ${{ github.workspace }} # PYTHONPATHの設定
    # ステップの設定
    steps:
      - name: Checkout
        uses: actions/checkout@v4 # リポジトリを利用できるようにするためのアクション
      - name: Setup Python
        uses: actions/setup-python@v5 # 自動テストで利用するPythonのセットアップを行うアクション
        with:
          python-version: 3.11 # Pythonのバージョンの指定
      - run: |
          python -m pip install --upgrade pip # ライブラリ管理ツールのアップデート
          pip install -r requirements.txt # ライブラリのインストール
          pytest tests # テストの実行
  build-and-push: # DockerイメージのビルドとECRへのプッシュのジョブ
    needs: tests # テストジョブが成功した場合のみ実行
    runs-on: ubuntu-latest # 実行環境(ランナー)の指定
    permissions: # 権限の設定
      id-token: write # ECRへのプッシュするために必要な権限
      contents: read # 認証を行う際に、リポジトリのコンテンツを読み取るために必要な権限
    steps:
      - name: Checkout
        uses: actions/checkout@v4 # リポジトリを利用できるようにするためのアクション
      - uses: aws-actions/configure-aws-credentials@v1 # AWSの認証情報を設定するアクション
        with:
          aws-region: ${{ secrets.AWS_REGION }} # AWSのリージョンの指定
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }} # 認証に利用するロールのARNの指定
      - name: Docker build and push
        run: |
          docker build -t github-actions-sample . # Dockerイメージのビルド
          docker tag github-actions-sample:latest ${{ secrets.IMAGE_REPOSITORY }}/github-actions-sample:latest # イメージのタグ付け
          aws ecr get-login-password --region ${{ secrets.AWS_REGION }} | docker login --username AWS --password-stdin ${{ secrets.IMAGE_REPOSITORY }} # ECRへのログイン
          docker push ${{ secrets.IMAGE_REPOSITORY }}/github-actions-sample:latest # ECRへのプッシュ

Yamlファイルを作成時に重要ポイント

以下の部分を確認して下さい。
- 最重要な事柄（GitHubActionsを利用する際に必ず必要になる項目）
  - name: ワークフローやステップの名前を記載する。
  - on: イベントトリガーを設定する。
    - on:の後に記載するのが、イベントトリガーになります。ここでは、push(プッシュした際にワークフローを実行)
    - branches: イベントを紐づけるブランチ名を記載。サンプルでは、mainブランチ
  - jobs：各ジョブを記載する。サンプルでは、以下のジョブを設定しています。
    - tests: 自動テストを実行する。
    - build-and-push: コンテナイメージのBuildとECRへのデプロイを実行する。
  - runs-on: ランナーを設定します。
  - uses: 利用するアクションとアクションの実行に必要な値を記載します。
    - with: アクションを実行するために必要な引数を設定。どのような引数が設定されているかは、各種公式ドキュメントを参照して下さい。
  - run: 実行したいLinuxコマンドを記載します。
    - |(パイプ)を利用することで、複数行でコマンドを記載することができます。
- 状況によって必要になる事柄
  - needs: job同士の連携を記載します。
    - needsに記載されているジョブが正常終了するまで、自身のジョブを実行しないように設定できる。
  - env: ステップで利用する環境変数を設定します。
  - permissions: アクセス権限の設定を行う。
    - 今回は、AWSへの接続のため、id-tokenおよびcontentsを設定しました。

機密情報について

機密情報の取り扱いは、GitHubに事前に登録することで、Yamlファイルに記載しなくても利用することができます。
- 機密情報の例: 外部サービスを利用するためのToken
登録する方法は、以下の通りです。
1. リポジトリのHOME画面から「Setting」をクリック
2. リポジトリ設定画面に遷移するので、「Secrets and variables」をクリックする。
3. 表示される「Actions」ボタンをクリックする。
4. SecretsとVariables設定画面に遷移するので、「New repository secret」ボタンをクリックする。
5. NameとSecretを入力して、「Add secret」ボタンをクリックします。
6. 登録した機密情報は、下記のように利用することができます。yamlファイル上で、「secrets.登録したName」とすることで、登録したSecretの値を利用することができます。
```
 - uses: aws-actions/configure-aws-credentials@v1 # AWSの認証情報を設定するアクション
   with:
     aws-region: ${{ secrets.AWS_REGION }} # AWSのリージョンの指定
     role-to-assume: ${{ secrets.AWS_ROLE_ARN }} # 認証に利用するロールのARN
```