GitHub Actions 上で apt 使わず doxygen (など) を使いたい

apt を使った手順だと･･･

apt install を使ったワークフローがこちら。

# 抜粋
jobs:
  # Generate Doxygen doc for FW api
  build-fw-api:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: src_fw/platform-io

    steps:
    - name: Source checkout
      uses: actions/checkout@v4
    - name: Set up Doxygen
      run: sudo apt install -y doxygen
    - name: Generate FW document
      run: doxygen
    - name: Upload artifact
      uses: actions/upload-artifact@v4
      with:
        name: build-fw-api
        path: src_fw/platform-io/docs/html/
        retention-days: 1

この apt install が問題で、順調なときはそう問題にならないのですが･･･

しかし回線か何かの調子が悪くなると、これが一気に 1分超えという長さに。(4分超えを観測したことも)

パブリックリポジトリなら時間制限がないので放っておいてもよいのですが、時間が安定しないのは好ましくありません。しかし回線を安定させて apt を安定させるのは困難です。

ならば別の手で

「apt が不安定なら、apt 以外で Doxygen を導入すればいいじゃない。」

ということで、docker run を使った手がこちら。

# こちらも抜粋
jobs:
  build-fw-api:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: src_fw/platform-io

    steps:
    - name: Source checkout
      uses: actions/checkout@v4
    - name: Generate FW api document
      run: docker run --rm -v ./:/github/workspace -w /github/workspace ghcr.io/doxygen/doxygen:Release_1_14_0
    - name: Upload generated docs
      uses: actions/upload-artifact@v4
      with:
        name: build-fw-api
        path: src_fw/platform-io/docs/html/
        retention-days: 1

Doxygen 公式から出ている Docker コンテナを呼び出しています。これは Ubuntu イメージベースで、Doxygen がインストールされたイメージです。

設定ファイル Doxyfile がある場所をマウントし、doxygen をコンテナ上で実行し、ドキュメントを生成します。(entrypoint が doxygen なので追加引数なしで OK)

apt で順調なときよりも早い上に、極端に遅くなったこともありません。(10回以上動かして不調になったことなし)

ghcr.io からのイメージのダウンロードもネットワーク通信ですが、なぜかこっちは不安定になりません。

これにて一件落着。

付録

これらワークフローを動かしたのはこちらのリポジトリ。

マイコンボード NUCLEO-F303K8 のファームウェア (C言語) のドキュメントを、Doxygen で出力して Pages で公開しようとしていたところでした。その過程で、apt install が急に遅くなる現象に襲われ、docker run を試したのでした。

補足

ここでは Doxygen を扱いましたが、同様にして GitHub Actions Runner Image にプリインストールされていないソフトを、Docker 経由で使うことが可能です。

詳しい Docker の手順はこの記事の範囲を超えてしまうのでカットしますが、

1. ubuntu イメージなどをベースに、目的のソフトをインストールしたイメージを作る
2. Docker Hub や GitHub Container Registry (ghcr.io) などのレジストリに push する
3. 先のワークフローの docker run の工程で push した当該イメージのリンクを入力する

というような具合です。

何言ってるかわかんない･･･という方は、まずは Docker の何たるかについての基本、次に Dockerfile の書き方と docker build についてお勉強してみましょう。