GitHub Actionsを使って気軽にAsciiDocを出力しよう(2) | cloud.config Tech Blog

はじめに

前回の記事で環境構築が面倒だと考えられていたAsciiDocが気軽に利用できることを簡単に紹介しました。
今回は前回実際に利用したワークフローの内容に基づき本来PythonやRubyが必要な環境をなぜこんなに簡単に利用できるのか？を解説したいと思います。

今回の内容を通してお読みいただければワークフローをご自身で修正したり、新たなワークフローを作成できるようになります。

前回までの記事について

これまでの記事はこちらにあります。　
そちらも合わせてお読みいただけると嬉しいです。

本ページで利用するサンプルについて

前回の記事から利用しているリポジトリを僕の個人的なプロジェクトの一環で公開しています。
ご自身で全てご準備できなくても感覚を掴むことができます。

Analog-inc/asciidoctor-action-sample

ワークフローの大まかな流れ

GitHub ActionsのWorkflowの構成を前回実際に利用したワークフローの内容に基づきシンプルに表した図が以下になります。

それぞれにオプションの指定はありますが基本的な動作はこれで完結しています。

実際のコードからワークフローの流れを理解しよう

ここからは前回実際に利用したワークフローの内容を解説します。
ワークフローはYAMLファイルにGitHub Actionsのワークフロー構文で記載します。
ワークフローの内容は始めて触れる方でも分割して読めばそれほど難しくありません。
YAMLの構文やワークフロー構文を知りたい方は以下のヘルプを読んでいただくと理解が深まりますが、今回は使っているものだけ簡単に解説していきます。

GitHub Actionsのワークフロー構文

ワークフローの命名

まず最初にワークフローの名前を決めています。
今回は「CI」としています。

# This is a AsciiDoctor workflow to help you get started with Actions
name: CI

ワークフローの実行タイミング

こちらはワークフローをトリガーするタイミングを記述しています。
対象のリポジトリのmasterブランチにPushされると実行します。

# Controls when the action will run. Triggers the workflow on push 
# events but only for the master branch
on:
  push:
    branches: [ master ]

ワークフローのJob定義

ここからがワークフローで実際に実行される機能(job)になります。
jobは複数定義できますが、今回は唯一のjobを「asciidoctor_job」として定義(命名)し今後の処理を記載します。

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "asciidoctor_job"
  asciidoctor_job:

ワークフローを実行する仮想環境

ワークフロー内のジョブを実行するマシンとして仮想環境の新しいインスタンスが必要になります。
ここではそのインスタンスとなるホストランナーの仮想環境を定義します。「asciidoctor_job」では Linuxを利用するため「ubuntu」の最新版を指定し「Build AsciiDoctor」と命名しています。
(ホストランナーの仮想環境として他にもWindows、macOSなどの環境も指定することができます。)
この仮想環境で「steps」配下に定義したタスクを進めていきます。

    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    name: Build AsciiDoctor
    steps:

出力対象のadocファイルをcheckout

いよいよ最初の実処理です。
「actions/checkout」アクションを利用し自分のリポジトリの.adocファイルを含むソースコードをホストランナーの仮想環境上にチェックアウトします。
「@」以降の表記は利用するバージョンで記載することで、利用するバージョンを固定することができるため最新版の「v2」を指定しています。
今回はその他の引数を省略していますが、指定することで他のリポジトリのcheckoutも行うことができます。

このように多くの人が公開しているアクションを使うことで一見難しい処理をサクッと記述することができます。この後も他のアクションを利用し処理を進めていきます。

なお「actions/」で始まるアクションはgithub.com公式のverifiedアクションです。「actions/checkout」アクションの詳しい解説は下記をご覧ください。

Checkout

    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - name: Check out code
      uses: actions/checkout@v2

AsciiDocのHTML出力処理

こちらが出力処理です。
「Analog-inc/asciidoctor-action」アクションを利用します。
今回は「@」以降の表記はバージョンではなく「master」ブランチを指定しています。
重要なポイントとしてアクションの引数「shellcommand」として「asciidoctor README.adoc」を渡しています。
こちらのアクションの中身についてはとても重要なので、次回の記事で詳しく解説します。

「Analog-inc/asciidoctor-action」アクションは僕の個人的なプロジェクトの一環で公開しているアクションになります。アクションのページは以下となります。

Build AsciiDoctor Docker Action

    # Output command using asciidoctor-action
    - name: Build AsciiDoc step
      id: documents
      uses: Analog-inc/asciidoctor-action@master
      with:
        shellcommand: "asciidoctor README.adoc"

artifactへのアップロード

ホストランナーの仮想環境はジョブの実行が終わると消えてしまうためartifactに出力ファイルを保存する必要があります。
AsciiDoc出力後の処理としてホストランナーの仮想環境から出力後のHTMLファイルを取り出し保存します。

実際の処理としてはartifactにアップロードを行います。
そのために「actions/upload-artifact」アクションを利用します。
アクションの引数「name」として「Output-document」、「path」として「./README.html」を渡しています。
引数の指定によりartifactに「README.html」が入った「Output-document.zip」ファイルがアップロードされます。

こちらのアクションも「actions/」で始まるgithub.com公式のverifiedアクションです。「actions/upload-artifact」アクションの詳しい解説は下記をご覧ください。

Upload artifact

    # Use the output from the documents step
    - name: Save AsciiDoc step
      uses: actions/upload-artifact@v1
      with:
        name: Output-document
        path: ./README.html

まとめ

今回は前回利用したワークフローの流れを簡単に解説しました。
外部のアクションを利用すれば簡単にワークフローを利用できることをご理解頂けたかと思います。
次回以降は「Analog-inc/asciidoctor-action」の内容を説明するとともに、利用する外部アクションの安全性も簡単に解説したいと思います。