Github Pages x Hexo運用をGithub Actionsで自動化

Github Actionsを用いると、Gitにpushしたタイミングなどで、任意のコマンドを自動で実行させることができます。その機能を活用してGithub Pages x Hexoで生成されたWEBサイトの運用フローを自動化します。

今回自動化したい手順

  • 前提とするWEBサイトを生成するまでは以下の記事を参照して下さい

  • Hexoサイトの更新フロー

    • 記事を生成
      1
      hexo new '記事名'
    • 生成されたmdファイルを編集
    • hexo generateを実行
      • mdファイルからWEB公開用のHTML/JSを自動生成
    • ディレクトリ名を変更
      • Github Pagesはリポジトリ直下に置かれたファイルを読み込みます。そこでHexoディレクトリを読み込むとエラーが出るため、Hexoディレクトリの頭に_を付与して読み込めない状態にします
        1
        mv your-blog _your-blog
    • add/commitしてGitにpush
  • 以下の単純作業は人間がやる必要が無さそうなので自動化を試みます

    • hexo generateの実行
    • ディレクトリ名の変更

実装手順

ディレクトリ名の変更を自動化

まずは練習として、ディレクトリ名の変更だけGithub Actionsで実行させます。

  • Point

    • まずはGitのリポジトリからソースをGithub Actionsの仮想サーバーに持ってくる必要がある
    • Github Actions上でコマンドを実行して編集したソースは、リポジトリにpushで返す必要がある
  • Github PagesのActionsタブを選択

    • set up a workflow yourselfを押下

Github Actions

  • エディターが立ち上がります

Github ACtions Editor

  • 記載例

    • uses: actions/checkout@vでリポジトリの中身にアクセス可能になります
    • 次にgitコマンドを使う為にgit configを実行
    • git mvでHexoディレクトリの名称を変更
    • git add/commit後にpushでリポジトリに変換
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      # workflow name
      name: Hexo x Github Pages CI

      # masterへのpush時に発火する様に定義
      on:
      push:
      branches: [ master ]

      jobs:
      # This workflow contains a single job called "build"
      changeName:
      # The type of runner that the job will run on
      runs-on: ubuntu-latest

      # 1. GitのリポジトリからソースをGithub Actionsに環境に持ってくる
      # Steps represent a sequence of tasks that will be executed as part of the job
      steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      # 2. git mvでディレクトリ名を変更 ⇒ 変更したソースをGitに返す
      # Runs a single command using the runners shell
      - name: change directory name & return for git
      run: |
      git config user.name "<git-user-name>"
      git config user.email "<git-user-e-mail>"
      git remote set-url origin https://:${{ secrets.GITHUB_PASS }}@github.com/<organization-name>/<your-repository-name>
      git mv your-blog _your-blog
      git add *
      git commit -m "Change directory name!"
      git push origin master
  • 記載後に”start commit”を押下

    • workflowを定義したymlファイルが生成されます
  • 一旦ローカルに反映

    1
    git pull
  • 以後masterにpushする度にworkflowが自動で実行されます

  • Actionsタブから確認出来る実行結果にチェックマークがついていれば成功です

actions result

  • 今回は分かり易く、Github Actionsタブから編集しましたが、ローカルリポジトリでymlファイルを生成してリモートにpushしてもOK

Github Actionsでworkflowを開発する際のデバッグ

  • Actionsタブのjob名から実行結果を確認出来ます

    • ここに出ているのは、Github Actionsで立ち上がった仮想サーバーの中のできごとです
      • GithubをMicrosoftが買収したこともあって、裏はAzureの仮想サーバー(Linux)です
    • Github Actionsの中でgitコマンドを実行させようとしていますが、アカウント名などを設定できていないために失敗しており、git configも実行させないとダメそうだ、と分かります

Debug workflow

hexo generateを自動化

次に、先ほどのテンプレートに、Generateを実行するくだりも追加します。Hexoコマンドを

  • Point

    • Hexoコマンドを実行するためには、先にNode.jsの環境構築が必要
      • Github Actionsで立ち上がる仮想サーバーは、毎回まっさらな何も入っていないLinuxです
  • 公開アクションの検討

    • Github actions marketplace hexo
    • こちらの公開アクションも使ってみたのですが、バージョンの問題か失敗しました。今回は簡単なので自前で作ります。
  • 以下のworkflowでhexo generateも自動化できました

    • remote set-url以降で自分のリポジトリを指定する箇所だけ読み替えて利用してください
  • hexo_cicd.yml

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    # workflow name
    name: Hexo x Github Pages CI

    # master push時に発火
    on:
    push:
    branches: [ master ]

    jobs:
    # This workflow contains a single job called "build"
    changeName:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # 1. GitのリポジトリからソースをGithub Actionsに環境に持ってくる
    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v2

    # 2. 公開アクションでNode.js動作環境を構築
    - name: Setup Node.js environment
    uses: actions/setup-node@v1.4.2

    # 3. Hexoディレクトリでhexo gを実行
    - name: use hexo
    run: |
    cd your-blog
    npm install
    npm install -g hexo
    hexo g
    cd ..

    # 4. git mvでディレクトリ名を変更 ⇒ 変更したソースをGitに返す
    # Runs a single command using the runners
    - name: change directory name & return for git
    run: |
    git config user.name "<git-user-name>"
    git config user.email "<git-user-e-mail>"
    git remote set-url origin https://:${{ secrets.GITHUB_PASS }}@github.com/XXXXXXXX/XXXXXXXX.github.io
    git mv your-blog _your-blog
    git add *
    git commit -m "Generate & Change directory name!"
    git push origin master

リポジトリにパスワードを埋め込む

私の環境では不要でした。

  • リポジトリのセキュリティ制約が厳しい場合
    • Github Actionsの仮想サーバー上からリポジトリと通信するには、gitのパスワードが必要になります。workflowに直接書き込んでしまうと、Public Repositoryなら誰でも見れてしまうので、Settingsに登録して参照させます

image

  • 参照方法
    • github actionsのworkflowに以下のように書けば値を引っ張れます
      1
      ${{ secrets.GITHUB_PASS }}

関連記事

参考

[CI/CD入門] Github Actionsでビルド/テスト/デプロイを自動化

Github Actionsというサービスを活用して、開発フローの一部を自動化する手法を勉強したので、まとめておきます。今後のデファクトになりそうな便利ツールなので覚えて損はないと思います。

CI/CDとは

開発の効率化を目的とした、以下の思想を指します

  • CI (継続的インテグレーション)
    • テスト, ビルド等を自動化して小まめに行う
  • CD (継続的デリバリー)
    • 本番環境へのデプロイを自動化して小まめに行う

上記を実現するために様々なツール(ex. jenkins, Circle CI…)があり、Githubと連携させて利用するのが一般的です。2020にGithubが自ら打ち出した新たなサービスがGithub Actionsです。

Github Actions解説

概要

  • Github Actions
    • Githubが提供している機能の一つ
    • 機能:ワークフローの自動化
      • pushやmergeを起点に自動で何らかのアクションを実行
      • ex. テストの自動化、Buildの自動化、本番環境へのデプロイの自動化
    • ymlファイル形式でワークフローを定義して使う

workflow

  • 魅力
    • 工数削減
      • 従来のようにGitと他のツールを連携させる手間が無くなる。学習コストや設定にあける工数を削減可能
    • 再利用性
      • 作成したWrokflowをGitでそのまま管理して、使いまわせる
      • 公開アクションが充実しており、よくあるフローは大抵用意されている

公開アクションの利用方法

Actions

料金

  • Publicリポジトリ

    • 無料
  • Privateリポジトリ

    • 従量課金性
      料金
  • 大規模開発でなければ、無料で使えそう

注意点

  • Github Enterpeise Cloudには対応済みだが、Github Enterprise Serverは未対応(2020\06時点)

    • Github社に問い合わせたところ、2020後半に対応予定とのこと
  • 契約プラン

    • レガシープランユーザの場合利用できないらしいので、会社で利用している方は要確認。リポジトリにActionタブが無い場合はレガシープランかもしれません。
      • 公式説明
        1
        Github Actionsはレガシープランユーザはご利用できません。

実行環境

  • 裏側でVM(仮想サーバー)が立ち上がり、そこで処理を実行してくれます
  • OS
    • Linux/Windows/macOSから選んで利用可能
      • これもテンプレートで設定します
    • LinuxやWindowsについては、MicorosoftがGithubを買収した経緯もあり、Azure上で動くようです

ワークフローの定義

  • 定義方法
    • リポジトリにworkflowディレクトリを作成
      1
      .github/workflows/
    • YAMLファイルを配置
      • ここにワークフローを定義
      • ファイルがワークフローの単位となる
      • ファイルは複数可、並列で実行される

ワークフロー(YAMLファイル)の構造

1
2
3
4
5
ワークフロー(YAMLファイル)
└ jobs:
└ ジョブ(名前は任意)
└ steps:
└ アクション

Job

  • 各ジョブは仮想環境の新しいインスタンスで実行される。
  • ジョブ間で環境変数やファイル、セットアップ処理の結果などは共有されない。
  • ジョブ間の依存を定義して待ち合わせることができる。
  • データの受け渡しが必要ならアーティファクト経由

Step

  • Jobが実行する処理の集合。
  • 同じJobのStepは同じ仮想環境で実行されるのでファイルやセットアップ処理は共有できる。しかし各ステップは別プロセスなのでステップ内で定義した
  • 環境変数は共有できない。
    • jobs..envで定義した環境変数は全Step で利用できる

開発フローの検討

分散開発におけるGit flowを検討しました

例:S3(AWS)でAPをHostngしているケースの作業

  • APを改修して、本番環境に変更を反映するまでに必要な作業

    1. 開発
    2. gitへpush
    3. PullRequest レビュー ⇒ Master Merge
    4. Build
    5. 本番環境へデプロイ
  • Masterが更新される度に、Buildしてデプロイする単純作業(4 & 5)を自動化したい

  • やり方は2通りありそう

    • Github Actionsでbuildとdeployを実行
    • GithubからはWebhookのみ、AWS上でCode Builderを起動させてBuild、Code Deployでdeployを実行

Github Actionsを利用した開発フロー

CI/CD開発のイメージ

  1. 個人で担当箇所を開発
  2. Gitの個人Branchにpush
  3. Pull Request レビューを実施
  4. Masterへmerge
  5. Github Actionsが起動
    • Buildを実行
    • (KarmaによるE2Eテストを実行)
      • テストについての解説は今回は省略します
    • 本番環境(etc. S3/Firebase…)へデプロイ
    • Slack or Teamsに通知(ここはWebhookやNotificationを使ってもOK)

実装

使い方

  • workflowを定義したymlファイルを作ります
    • 以下のように配置したymlファイルが読み込まれます
      1
      your-repository\.github\workflows\sample.yml
  • workflowの生成方法(以下のどちらか)
    • Githubのブラウザ(Actionタブ)から設定
    • Local Repositoryでディレクトリ毎生成してpush

Githubブラウザ側で設定

  • Githubの任意のリポジトリのActionタブで設定を行う
    • Github Enterpriseを利用中でActionタブが無い場合
      • レガシープランユーザーの可能性があるので、契約の確認が必要
        • 公式説明
          1
          GitHub Actionsはレガシープランユーザーではご利用できません。

Github Actions

  • ブラウザでそのままディレクトリとwrokflowファイルを生成できます
    • set up a workflow yourselfを押下すると以下の様画面に飛びます

Workflow編集画面

  • Actionsタブを確認
    • 先ほど生成されたworkflowが実行されていることが分かります
    • New workflowを押下してworkflowを追加していけます

Actionsタブ

Loacalリポジトリで作業する場合

  • ディレクトリを作成

    1
    your-repository> mkdir .github/workflows/
  • YAMLファイルを作成

    • 名称の規則は無し
      1
      your-repository.github/workflows/> touch sample.yml
  • そのままymlファイルを編集してGitにpushすれば、Github Actionsが動くようになります

Workflowテンプレートの開発

  • AngularアプリをBuildして、AWSのS3にデプロイするワークフローの例
    • 解説は後述します
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      name: Angular CI/CD ## workflow名を設定
      on: ## workflowのTriggerを定義
      push: ## push時に発火 他例) pull request
      branches: ## 条件でmaster branchへのpushに限定
      - master

      jobs: ## ここで実行するジョブを指定
      build: ## buildという名目のジョブを定義
      ## 実行環境 Github Actions提供の仮想サーバー
      runs-on: ubuntu-latest ## Ubuntsの最新版環境を指定
      strategy:
      matrix:
      node-version: [12.x]

      steps: ## 以降に実行する処理/コマンドを定義

      ## github actionsの環境にリポジトリのソースを持ってくる
      - uses: actions/checkout@v2

          ## 環境構築  
          - name: Angular Github Actions
            # 公開アクションでangular動作環境を構築 
            uses: mayurrawte/github-angular-actions@latest

          ## CI: Build
          - name: Build ## アクション名
            ## 実行するコマンド
            run: ng build --prod

      ## CD: S3にデプロイ
          - name: S3 site action
            uses: erangeles/s3-site-action@v1.0

      ## Github Actions環境で処理後のソースをGitに返す
      # Runs a single command using the runners
      - name: change directory name & return for git
      run: |
      git config user.name "<git-user-name>"
      git config user.email "<git-user-e-mail>"
      git remote set-url origin https://:${{ secrets.GITHUB_PASS }}@github.com/XXXXXXXX/XXXXXXXX.github.io
      git add *
      git commit -m "Generate & Change directory name!"
      git push origin master

Triggerを指定

  • on: でworkflowが発火するタイミングを指定できます
    • 以下はmaster mergeの実行時を指定
      1
      2
      3
      4
      on:  ## workflowのTriggerを定義
      push: ## push時に発火 他例) pull request
      branches: ## 条件でmaster branchへのpushに限定
      - master

実行環境を設定

  • Github Actionsは裏側でVM(仮想サーバー)が動きます
    • 今回はLinux (Ubunts)を設定
    • WindowsやMacOS等、一通り揃っています
1
2
3
4
5
## 実行環境 Github Actions提供の仮想サーバー
runs-on: ubuntu-latest ## Ubuntsの最新版環境を指定
strategy:
matrix:
node-version: [12.x]

actionの設定

  • ワークフローの最小単位

  • 2種類ある

    • run
      • コマンドを実行
    • uses
      • Githubやサードパーティの公開actionを利用
  • 設定の流れ

    • まず公開のアクションがないか探してみる
    • なければ実行したいコマンドをrunで設定

checkout

  • まずはgithub actionsで利用する仮想サーバーにリポジトリのソースコードを持ってくる必要があります
    • Githubが事前に公開アクション(actions/checkout@v2)を用紙してくれているので、そちらを使います
1
2
## github actionsの環境にリポジトリのソースを持ってくる
- uses: actions/checkout@v2

環境設定

  • Angularのコマンドを実行するためにNode.jsやAngular CLIをinstallする必要があります

    • 今回は公開アクションで両方終わらせていますが、それぞれ設定する際の例を以下に示します
      • 効果アクションはバージョンによって動かなくなるリスクもあるので念のため
  • 参考

  • Nodejs動作環境を公開アクションで構築

    1
    2
    - name: Setup Node.js environment
    uses: actions/setup-node@v1.4.2
  • angular CLIをrunでinstall

    1
    2
    3
    ## 環境構築が必要
    - name: install
    run: npm install -g @angular/cli

build

  • runでbuildコマンドを実行
    1
    2
    3
    4
    5
    ## -----CI(継続的インテグレーション)----
    ## Buildするアクション
    - name: Build ## アクション名
    ## 実行するコマンド
    run: ng build --prod

処理実行後にpush

  • Github Actions環境(仮想サーバー)で処理したため、リポジトリへpushで反映する必要がある
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    ## Github Actions環境で処理後のソースをGitに返す
    # Runs a single command using the runners
    - name: change directory name & return for git
    run: |
    git config user.name "<git-user-name>"
    git config user.email "<git-user-e-mail>"
    git remote set-url origin https://:${{ secrets.GITHUB_PASS }}@github.com/XXXXXXXX/XXXXXXXX.github.io
    git add *
    git commit -m "Generate & Change directory name!"
    git push origin master

Github Actionsのステータス

  • Actionsタブのjob名から実行結果を確認出来ます

    • ここに出ているのは、Github Actionsで立ち上がった仮想サーバーの中のできごとです
      • GithubをMicrosoftが買収したこともあって、裏はAzureの仮想サーバー(Linux)です
  • 実行時
    In progress

  • workflowを開発のデバッグ例

    • Github Actionsの中でgitコマンドを実行させようとしていますが、アカウント名などを設定できていないために失敗しており、git configも実行させないとダメそうだ、と分かります

Debug workflow

所感

他の方もおっしゃっているように、Github Actionsはworkflowの書式が簡単で、即日で使いこなせる”手軽さ”が魅力的でした (jenkins等はもっと学習コストがかかるイメージ)
ディレクトリ毎コピーするだけで簡単に再利用できるため、開発チーム内で貯めていけば、より効果を発揮しそうです。

参考

関連記事 (本番環境へのデプロイまで)

Github Actions

S3

@EventEmitter @Input @Output @ViewChild ACM AMP API Gateway AR AR.js AR.js Studio AWS AWS Amplify AWS Budgets AWS Cost Explorer AWS SDK for JavaScript AddThis Adobe XD Alexa Amazon CloudWatch Amazon Honycode Amazon SNS Android Angular Angular Material AngularFire AppSync Augury C CDN CI/CD Cloud Craft Cloud9 CloudFormation CloudFront CloudTrail Cognito Cost Anomaly Detection Cubase ai Cubasis LE DTM Disqus DynamoDB Elgato HD 60S Firebase Firebase Hosting Former2 Github Github Actions Github.com GithubEnterprise GithubPages Google Chrome Google Cloud Shell GraphQL Hexo Hosting IAM Ionic JSON JavaScript LadioCast Logging LowCode MFA MS Authentication MacBook Pro 16 Mind Node NETDUETTO Netflix Party Netlify Network NoCode Observable PO PdM Promise RPA ReactiveForm Recognition Route53 S3 SAM(Serverless Application Model) SAR SSL SYNCROOM Schematics ScrumInc Serverless Service Siri Sitemap Spark AR Steinberg UR44C Teams Touch Cast Studio Treetable TypeScript UI UI Bakery WAF WAFv2 WEB Page Dev WEB会議 WebAR WebSocketAPI Webhook Windows Power Automate Wireshark aot async/await aws config cloud9 display.land draw.io e2e test filter() forkJoin() google search console hexo-generator-amp iOS iPad Pro iPhone icarus map() mat input mat tree mat-checkbox mat-input mat-selection-list mmhmm ngFor plantUML popIn Aladdin2 then() vscode ”global is not defined” らくがきAR アジャイル アジャイル開発 クロスプラットフォーム ショートカット スクラム スクラム開発 テレワーク ファイル操作 ブラウザ型IDE プロダクトオーナー プロダクトマネージャー プロトタイピング リモートセッション 共同開発 双方向データバインディング 待ち合わせ処理 認定スクラムマスター 静的WEB Hosting 静的WEBサイトHosting
Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×