GitHub ActionsのAsciiDoc用アクションの仕組み(1) | cloud.config Tech Blog

はじめに

前回の記事で環境構築が面倒だと考えられていたAsciiDocが気軽に利用できることを簡単に紹介しました。
今回からは前回まで利用した「Analog-inc/asciidoctor-action」の内容の解説を通してアクションの利用方法に理解を深めるとともに、利用する外部アクションの安全性も解説したいと思います。

今回からの内容を通してお読みいただければ、ご自身でワークフローから共通的に利用できる簡単なアクションを作れるようになると思います。

前回までの記事について

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

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

前回の記事から利用しているリポジトリは僕の個人的なプロジェクトの一環で公開しています。

呼び出し元の処理のおさらい

こちらは実際のワークフローから「Analog-inc/asciidoctor-action」アクションを呼び出している部分です。
ワークフロー全体の詳しい説明は以下のリンクをご参照ください。

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

「Analog-inc/asciidoctor-action」アクションについて

ワークフローからアクションを呼び出す処理はGitHubのリポジトリを参照することで行われます。今回説明するアクションは「Analog-inc/asciidoctor-action」リポジトリに実体があります。
実際にその中身を見てみましょう。

Analog-inc/asciidoctor-action

※ 今回は公開しているアクションの利用を前提に解説しますが、アクション自体は非公開での利用も可能です。詳しくは下記のリンクをご参照ください。

アクションの場所を選択する

アクションを構成するファイル

ここには、以下の8つのファイルがあります。
これらの中で実際にアクションの処理を行うファイルは「Dockerfile」「action.yml」「entrypoint.sh」の３つのみとなります。
「Dockerfile」「entrypoint.sh」はアクションの中でコンテナやその動作を定義するファイルです。この2つのファイルは次回解説します。
今回はアクションの入り口となる「action.yml」の解説をしたいと思います。

into.github:workflows (サンプルのワークフローのファイル)
.gitignore : (Gitの管理に含めないファイルを指定するためのファイル)
Dockerfile : (AsciiDoctorコマンドを利用するコンテナ)
LICENSE : (アクションのライセンス)
README.adoc : (アクションのREADME)
_config.yml : (Marketplaceでのテーマの指定)
action.yml : (アクションの実体となるファイル)
entrypoint.sh : (コンテナ内で実行されるシェルスクリプト)

アクションの大まかな流れ

「Analog-inc/asciidoctor-action」アクションの構成のシンプルな図が以下になります。

それぞれにオプションの指定はありますが基本的な動作はこれで完結しています。
詳しい構文を知りたい方は以下のヘルプを読んでいただくと理解が深まりますが、今回は使っているものだけ簡単に解説していきます。

公開用の設定を行う

こちらはGitHub Marketplace内で表示されるアクションの名称やアクション名の隣に表示されるバッジとなるアイコンの設定を行なっています。
名称『name』を「Build AsciiDoctor Docker Action」としています。
アクションをパーソナライズして見分けられるようにするために、『branding』配下の『icon』にFeatherアイコンから「book-open」を指定し、『color』に「white」を選んでいます。なお、アイコンは以下のリンクから選ぶことができます。
最後に簡単な説明として『description』に「AsciiDoc Build action」と書いています。

Simply beautiful open source icons

name: 'Build AsciiDoctor Docker Action'
branding:
  icon: 'book-open'  
  color: 'white'
description: 'AsciiDoc Build action'

アクションの引数を定義する

こちらはワークフローからアクションを利用する際に必要な引数の定義をしています。
まず引数(の名称)を「shellcommand」として定義します。
引数の説明として『description』に「AsciiDoc Build command」を、
引数の必須(省略不可)として『required』に「true」を、
引数を省略された時のデフォルト値として『default』に「asciidoctor index.adoc」を指定しています。

引数の省略ができないのに、デフォルト値を持っていることについてはアクションを作った僕にも謎なので触れないでください。

inputs:
    shellcommand:  # id of input
        description: 'AsciiDoc Build command'
        required: true
        default: 'asciidoctor index.adoc'

Dockerコンテナを起動して引数を渡す

最後に実行部分の定義として実際にAsciiDocを出力する環境となるDockerコンテナを指定します。
実行環境としてDockerコンテナを利用するため『using』に「docker」を、
利用するコンテナイメージを指定する『image』にはアクションのリポジトリ内にある「Dockerfile」を、
引数としてアクションの引数をそのまま渡せるように『args』に「- ${{ inputs.shellcommand }}」を指定しています。

runs:
    using: 'docker'
    image: 'Dockerfile'
    args:
        - ${{ inputs.shellcommand }}

まとめ

今回は前回利用したアクションの大まかな内容を簡単に解説しました。
外部のアクションのどこをみれば引数など詳しく理解しながら利用できるかをご理解頂けたかと思います。
次回は「Analog-inc/asciidoctor-action」で利用するDockerコンテナについて説明したいと思います。