ビルドアーティファクトの保存

1+ year ago1 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

このドキュメントでは、CircleCI でのアーティファクトの取扱方法について説明します。 アーティファクトは、ジョブまたはパイプラインの完了後にデータを永続化するために使用します。 たとえば、ドキュメントやその他アセットの構築や、詳しい調査のためのテスト結果の保存などです。

アーティファクトの概要

アーティファクトには、ジョブが完了した後もデータが保持され、ビルドプロセス出力を格納するストレージとして使用できます。

たとえば、Java のビルドやテストのプロセスが 1 つ終了すると、そのプロセスの出力は .jar ファイルとして保存されます。 CircleCI では、このファイルをアーティファクトとして保存し、プロセスの終了後も使用可能な状態に維持できます。

アーティファクトのデータフロー

アーティファクトのもう 1 つの例として、Android アプリとしてパッケージ化されるプロジェクトがあり、この場合は、.apk ファイルが Google Play にアップロードされます。

ジョブによってスクリーンショット、カバレッジレポート、コアファイル、デプロイ tarball などの永続的アーティファクトが生成される場合、CircleCI はそれらを自動的に保存およびリンクします。

CircleCI Web アプリでパイプラインの Job ページに移動し、Artifacts タブを見つけます。 アーティファクトは Amazon S3 に保存され、プライベートプロジェクト用の CircleCI アカウントを使用して保護されます。 curl ファイルのサイズは 3 GB に制限されています。

Artifacts タブのスクリーンショット

デフォルトのアーティファクトの保存期間は 30 日間です。 保存期間は、 CircleCI Web アプリPlan > Usage Controls からカスタマイズ可能です。 現在、設定できる保存期間の最大値が 30 日間となっています。

ネットワークとストレージ使用量の管理の詳細については、 データの永続化のページを参照してください。

注: アップロードされたアーティファクトのファイル名は、 Java URLEncoder を使用してエンコードされます。 アプリケーション内の特定のパスにあるアーティファクトを探すときには、この点にご注意ください。

アーティファクトのアップロード

ビルド時に作成したアーティファクトをアップロードするには、以下の例を参考にしてください。

version: 2.1
jobs:
  build:
    docker:
      - image: python:3.6.3-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

    working_directory: /tmp
    steps:
      - run:
          name: Creating Dummy Artifacts
          command: |
            echo "my artifact file" > /tmp/artifact-1;
            mkdir /tmp/artifacts;
            echo "my artifact files in a dir" > /tmp/artifacts/artifact-2;

      - store_artifacts:
          path: /tmp/artifact-1
          destination: artifact-file

      - store_artifacts:
          path: /tmp/artifacts

この store_artifacts ステップによって、ファイル (/tmp/artifact-1) とディレクトリ (/tmp/artifacts) の 2 つのビルドアーティファクトがアップロードされます。 アップロードが正常に完了すると、ブラウザー内の Job ページの Artifacts タブにアーティファクトが表示されます。 大量のアーティファクトをまとめてアップロードする場合は、 単一の圧縮ファイルとしてアップロードすることで高速化できます。 1 つのジョブで実行できる store_artifacts ステップの数に制限はありません。

現在、store_artifacts には pathdestination の 2 つのキーがあります。

  • path は、アーティファクトとしてアップロードされるファイルまたはディレクトリのパスです。
  • destination (オプション) は、アーティファクト API でアーティファクトパスに追加されるプレフィックスです。 path で指定されたファイルのディレクトリがデフォルトとして使用されます。

コアファイルのアップロード

このセクションでは、 コアダンプを取得し、検査やデバッグで使用するためにアーティファクトとしてプッシュする方法について説明します。 以下の例では、 abort(3) を実行してプログラムをクラッシュさせる短い C プログラムを作成します。

  1. 以下の行を含む Makefile を作成します。

      all:
        gcc -o dump main.c
    
  2. 以下の行を含む main.c ファイルを作成します。

      # <stdlib.h> を含めます
    
      int main(int argc, char **argv) {
          abort();
      }
    
  3. 生成されたプログラムで make./dump を実行し、Aborted (core dumped) を出力します。

このサンプル C abort プログラムをコンパイルし、コアダンプをアーティファクトとして収集する config.yml の全文は、以下のようになります。

version: 2.1
jobs:
  build:
    docker:
      - image: gcc:8.1.0
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    working_directory: ~/work
    steps:
      - checkout
      - run: make
      - run: |
          # tell the operating system to remove the file size limit on core dump files
          ulimit -c unlimited
          ./dump
      - run:
          command: |
            mkdir -p /tmp/core_dumps
            cp core.* /tmp/core_dumps
          when: on_fail
      - store_artifacts:
          path: /tmp/core_dumps

ulimit -c unlimited により、コアダンプファイルのファイルサイズ制限がなくなります。 この制限がなくなると、プログラムがクラッシュするたびに、作業中のディレクトリにコアダンプファイルが作成されます。 コアダンプファイルには、core.%p.%E という名前が付きます。 %p はプロセス ID、%E は実行可能ファイルのパス名です。 詳細については、/proc/sys/kernel/core_pattern で仕様を確認してください。

最後に、store_artifacts によってアーティファクトサービスの /tmp/core_dumps ディレクトリにコアダンプファイルが格納されます。

アーティファクトページに表示されたコアダンプファイル

CircleCI がジョブを実行すると、Job ページの Artifacts タブにコアダンプファイルへのリンクが表示されます。

ビルドのすべてのアーティファクトのダウンロード

curl を使用してアーティファクトをダウンロードするには、以下の手順を実行します。

  1. こちらの手順通りにパーソナル API トークンを作成し、クリップボードにコピーします。

  2. ターミナルウィンドウで、アーティファクトを保存するディレクトリに cd します。

  3. 以下のコマンドを実行します。 : で始まる変数は、コマンドの下に掲載した表を参照して、実際の値に置き換えてください。

# Set an environment variable for your API token.
export CIRCLE_TOKEN=':your_token'

# `curl` gets all artifact details for a build
# then, the result is piped into `grep` to extract the URLs.
# finally, `wget` is used to download the the artifacts to the current directory in your terminal.

curl -H "Circle-Token: $CIRCLE_TOKEN" https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/artifacts \
   | grep -o "https://[^"]*" \
   | wget --verbose --header "Circle-Token: $CIRCLE_TOKEN" --input-file -

同様に、ビルドの_最新_のアーティファクトをダウンロードする場合は、curl の呼び出しを以下のように URL で置き換えます。

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/latest/artifacts?circle-token=:your_token

CircleCI の API を使用してアーティファクトを操作する詳しい方法については、 API リファレンスガイドを参照してください。

プレースホルダー意味
:your_token上記で作成した個人用の API トークン。
:vcs-type使用しているバージョン管理システム (VCS)。 github または bitbucket のいずれかとなります。
:usernameターゲットプロジェクトの VCS プロジェクトアカウントのユーザー名または組織名。 CircleCI アプリケーションの画面左上に表示されています。
:projectターゲット VCS リポジトリの名前。
:build_numアーティファクトをダウンロードする対象のビルドの番号。

アーティファクトストレージのカスタマイズ

セルフホストランナーを使用する場合、プランに含まれるネットワークとストレージ使用量には制限があります。 アーティファクトに関連するアクションには、ネットワークとストレージの使用が発生するものがあります。 お客様の使用量が制限を超えた場合、料金が発生します。

アーティファクトを長期間保存すると、ストレージコストに影響が及ぶため、アーティファクトを保存する理由を明確にすることをお勧めします。 アーティファクトを保存する利点の一つは、ビルドが失敗する原因のトラブルシューティングにアーティファクトを使用できることです。 ビルドに成功したら、そのアーティファクトはほぼ必要ありません。 ニーズに合う場合は、アーティファクトのストレージ保存期間を短く設定することを推奨します。

CircleCI Web アプリPlan > Usage Controls に移動し、アーティファクトのストレージ使用量や保存期間をカスタマイズすることができます。 ネットワークとストレージ使用量の管理の詳細については、 データの永続化のページを参照してください。

アーティファクトの最適化

アップロードされているアーティファクトの確認

実際に必要なファイルがわずかでも、store_artifacts ステップが大きなディレクトリで使用されているケースがよくあります。その簡単な対策として、どのアーティファクトがなぜアップロードされているかをご確認ください。

ジョブで並列実行を使用している場合は、各並列タスクが同じアーティファクトをアップロードしている可能性があります。 実行ステップで CIRCLE_NODE_INDEX 環境変数を使用して並列タスクの実行に応じてスクリプトの動作を変更することができます。

大きなアーティファクトのアップロード

テキスト形式のアーティファクトは、非常に低いコストで圧縮できます。 大きなアーティファクトをアップロードする必要がある場合、ご自身のバケットに 無料で アップロードすることが可能です。

UI テストのイメージや動画をアップロードする場合は、フィルタを適用して対象を絞り、失敗したテストのみをアップロードします。 多くの組織では UI テストからすべてのイメージをアップロードしていますが、その多くは使用されません。

パイプラインがバイナリまたは uberJAR をビルドしている場合、コミットのたびにそれが必要かどうかを検討してください。 フィルタを使用して失敗時または成功時のみアーティファクトをアップロードする、または単一のブランチにのみアーティファクトをアップロードすることが可能です。

テスト失敗時のみの結果のアップロード

when 属性を使用すると、設定のステップの結果に基づいてフィルタリングできます。 when 属性は on_successon_fail または always に設定できます。 失敗したテストのアーティファクトのみをアップロードするには、次のように when: on_fail 行をジョブに追加します。

steps:
  - run:
      name: Testing application
      command: make test
      shell: /bin/bash
      working_directory: ~/my-app
      no_output_timeout: 30m
      environment:
        FOO: bar

  - run: echo 127.0.0.1 devhost | sudo tee -a /etc/hosts

  - run: |
      sudo -u root createuser -h localhost --superuser ubuntu &&
      sudo createdb -h localhost test_db

  - run:
      name: Upload Failed Tests
      command: curl --data fail_tests.log http://example.com/error_logs
      when: on_fail

次のステップ