Twilio FunctionsをGitHub Actionsから自動デプロイする

はじめに

Git で管理している Twilio Functions の JavaScript コードを、GitHub Actions から自動デプロイする手順を紹介します。デプロイには Twilio Serverless Toolkit の twilio-run を使います。GitHub Actions Secrets を用いて、秘密情報をリポジトリに入れずに運用します。

Twilio とは

Twilio は、SMS や音声通話などのコミュニケーション機能を API として提供するクラウドサービスです。アプリケーションから Twilio の API を呼ぶことで、通信機能を組み込めます。Twilio Functions を使用すると、Twilio のサーバーレス環境で Node.js のコードを実行できます。HTTP エンドポイントとして公開でき、サーバー運用を意識せずにコードを動かせます。

対象読者

• Twilio Functions の手動デプロイをやめたい方
• GitHub Actions で main ブランチから dev 環境へデプロイしたい方
• 秘密情報を Git に入れずに運用したい方

参考

• Continuous Deployment using the Serverless Toolkit
• Deploying with the Serverless Toolkit
• Configuration and Meta Files

構成

GitHub リポジトリで管理している Twilio Functions のコードを、GitHub Actions から Twilio にデプロイします。

main ブランチへの push を契機に workflow を起動し、GitHub Actions Secrets に保存した認証情報と環境変数を実行環境へ注入します。twilio-run は注入された認証情報を使って、Twilio 上の Service test-function-ci の dev 環境へ Functions と Assets をデプロイします。

実装

Twilio Console で Service を作成する

CI/CD からのデプロイは、デプロイ先の Service を特定して上書きします。本記事では、Twilio Console 上で Service を先に作っておき、CI/CD は既存 Service に対してデプロイする前提にします。

今回は Service 名を test-function-ci として検証を行います。以降の設定で、この Service 名を参照します。Service 名は .twilioserverlessrc で serviceName として指定できます。

API Key と API Secret を用意する

Keys & Credentials > API keys & tokens メニューから API Key を作成します。

リポジトリ構成を用意する

Serverless Toolkit は、決まったディレクトリ構成で Functions と Assets を扱います。最小の例を次に示します。

.
├─ functions
│  └─ hello.js
├─ assets
│  └─ index.html
├─ .env.example
├─ .twilioserverlessrc
└─ package.json

今回は検証のため functions/hello.js を次のように用意します。

exports.handler = async function (context, event, callback) {
  callback(null, { ok: true });
};

twilio-run を追加する

Twilio は CI/CD 用途では twilio-run を devDependency として入れる構成を推奨しています。(参考)

次のコマンドで追加します。twilio-run は 3.0.0 以上にします。(筆者環境では 5.0.0 でした。)

npm install --save-dev twilio-run

package.json の scripts に deploy を用意します。CI/CD では twilio-run を直接呼ばず、npm run deploy で実行するようにします。

{
  "scripts": {
    "deploy": "twilio-run deploy --username $TWILIO_API_KEY --password $TWILIO_API_SECRET"
  },
  "devDependencies": {
    "twilio-run": "^5.0.0"
  }
}

.env.example を作成する

CI/CD では Secrets から環境変数を注入するのが一般的です。一方で、Serverless Toolkit は「どのキーをデプロイ環境へアップロードするか」を .env ファイルで判断します。そこで、値を含まないテンプレートとして .env.example を作ります。このファイルには、デプロイ環境へ反映したいキー名だけを書きます。

例として、APP_NAME をデプロイ環境へ反映する場合は次のようにします。

APP_NAME=

.twilioserverlessrc を作成する

次に、CI/CD で必要な設定を .twilioserverlessrc にまとめます。

• デプロイ先を test-function-ci に固定する
• デプロイ環境を dev に固定する
• .env.example に列挙したキーを GitHub Actions の環境変数から読み込む

loadSystemEnv と env を使うと、.env.example に書いたキーだけをシステム環境変数から拾ってデプロイ環境へ反映できます。

{
  "commands": {
    "deploy": {
      "serviceName": "test-function-ci",
      "environment": "dev",
      "overrideExistingProject": true,
      "loadSystemEnv": true,
      "env": ".env.example"
    }
  }
}

GitHub Actions の Secrets を設定する

GitHub のリポジトリ設定で Secrets を追加します。

• TWILIO_API_KEY
• TWILIO_API_SECRET
• APP_NAME (今回は例として test-function-ci-app と設定)

GitHub Actions workflow を追加する

目的は、main ブランチへの push を契機に npm run deploy を実行することです。次のファイルを .github/workflows/deploy.yml として追加します。

name: deploy-twilio-functions

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - run: npm run deploy
        env:
          TWILIO_API_KEY: ${{ secrets.TWILIO_API_KEY }}
          TWILIO_API_SECRET: ${{ secrets.TWILIO_API_SECRET }}
          APP_NAME: ${{ secrets.APP_NAME }}

検証

デプロイが成功することを確認する

main ブランチへ push し、GitHub Actions の job が成功することを確認します。ログ上でデプロイ先の Service が test-function-ci になっていることも確認します。

Function を呼び出して疎通する

デプロイ後、GitHub Actions のログで Function の URL を確認します。

(略)
functions
public /hello https://test-function-ci-****.twil.io/hello
(略)

curl でアクセスし疎通確認します。

curl -sS https://test-function-ci-****.twil.io/hello

{"ok":true}

環境変数が反映されていることを確認する

context.APP_NAME を参照するように hello.js を変更し、再度デプロイします。.env.example に列挙したキーが、GitHub Actions の環境変数から反映される動きになっていれば成功です。

hello.js

exports.handler = async function (context, event, callback) {
  const appName = context.APP_NAME || 'unknown';
  callback(null, { ok: true, appName });
};

疎通確認

curl -sS https://test-function-ci-****.twil.io/hello

{"ok":true,"appName":"test-function-ci-app"}

まとめ

twilio-run を使うと、Twilio Functions を GitHub Actions から自動デプロイできることを紹介しました。GitHub Actions Secrets を使用することで、秘密情報をリポジトリに入れずに運用できます。