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

以下のセクションに沿って、アーティファクトの操作方法を説明します。

アーティファクトの概要
アーティファクトのアップロード
コアファイルのアップロード
CircleCI で行うビルドのすべてのアーティファクトのダウンロード

アーティファクトの概要

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

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

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

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

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

[Artifacts (アーティファクト)] タブのスクリーンショット

アーティファクトへのリンクは、[Job (ジョブ)] ページの [Artifacts (アーティファクト)] タブに表示されます。アーティファクトは Amazon S3 に保存され、プライベートプロジェクト用の CircleCI アカウントを使用して保護されます。 curl ファイルのサイズは 3 GB に制限されています。

アーティファクトへは作成から30日間アクセスできます。 ドキュメントや永続的なコンテンツのソースとして依存している場合、S3や静的Webサイト用のGitHub Pages、Netlifyのような専用領域にデプロイすることを推奨します。

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

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

ビルド中に作成されるアーティファクトをアップロードするには、以下の例を使用します。

version: 2
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: ダミー アーティファクトの作成
          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 (アーティファクト)] タブにアーティファクトが表示されます。大量のアーティファクトをまとめてアップロードする場合は、単一の圧縮ファイルとしてアップロードすることで高速化できます。
単一のジョブで実行可能な store_artifacts ステップの数に制限はありません。

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

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

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

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

以下の行を含む Makefile を作成します。
```
  all:
    gcc -o dump main.c
```

以下の行を含む main.c ファイルを作成します。

  # <stdlib.h> を含めます

  int main(int argc, char **argv) {
      abort();
  }

生成されたプログラムで make と ./dump を実行し、Aborted (core dumped)! を印刷します。

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

version: 2
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: |
          # コア ダンプ ファイルのファイル サイズ制限をなくすようにオペレーティング システムに指示します
          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 (アーティファクト)] タブにコアダンプファイルへのリンクが表示されます。

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

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

パーソナル API トークンを作成し、クリップボードにコピーします。
ターミナルウィンドウで、アーティファクトを保存するディレクトリに cd します。
以下のコマンドを実行します。 : で始まる変数は、コマンドの下に掲載した表を参照して、実際の値に置き換えてください。

export CIRCLE_TOKEN=':your_token'

curl -H "Circle-Token: $CIRCLE_TOKEN" https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/$build_number/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`	アーティファクトをダウンロードする対象のビルドの番号。

コマンドの説明

まず、CIRCLE_TOKEN 環境変数を作成します。次に、curl コマンドでビルドのすべてのアーティファクト詳細をフェッチし、それを grep にパイプして URL を抽出します。 circle トークンでファイルの末尾に追加される sed を使用して、一意のファイル名を作成します。最後に、wget を使用してアーティファクトをターミナル内のカレントディレクトリにダウンロードします。

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