パイプラインのアーティファクト

概要

Artifacts are files that are produced by a step. Once you've defined them in your pipeline configuration, you can share or export them.

Artifacts enable teams to share outputs between sequential pipeline steps or preserve them after execution completes. Common use cases include passing build artifacts to deployment stages or retaining test reports.

Key Constraints

Important Limitations

Files must reside within BITBUCKET_CLONE_DIR at step completion
Glob patterns starting with * require quotation marks
Relative path notation ("." and "..") is unsupported
Artifacts created in parallel steps may not be accessible to other steps within the same group
Retention window: 14 days maximum
Size limit: 1 GB per artifact

Artifact Types

Shared Artifacts

Accessible across multiple steps. Use shared artifacts for workflows that require sharing data between steps.

pipelines:
  default:
    - step:
        name: Build
        artifacts:
          - dist/**
        script:
          - npm run build
    - step:
        name: Deploy
        script:
          - aws s3 sync dist/ s3://my-bucket/

Scoped Artifacts

Scoped to each step and can't be downloaded across steps. Ideal for files like log files, test reports, screenshots, or videos.

- step:
    name: Test
    artifacts:
      - name: Test Results
        type: scoped
        paths:
          - test-results/**
          - screenshots/**
    script:
      - npm test

Test Report Artifacts

XML-only format for test ingestion, confined to single step scope.

- step:
    name: Run Tests
    artifacts:
      - name: Test Reports
        type: test-report
        paths:
          - test-results/*.xml
    script:
      - npm test

基本的な構成

Simple Artifact

pipelines:
  default:
    - step:
        name: Build
        artifacts:
          - build/**
          - dist/**
        script:
          - npm run build

Named Artifact

- step:
    name: Build Application
    artifacts:
      - name: Production Build
        paths:
          - dist/**
          - build/**
    script:
      - npm run build

Artifact Syntax

Basic Syntax (Flat Glob List)

The most common form is a flat list of glob patterns:

- step:
    name: Build Application
    script:
      - npm run build
    artifacts:
      - dist/**
      - build/**

Structured Syntax

For more control, use the structured form with name and paths:

- step:
    name: Build Application
    script:
      - npm run build
    artifacts:
      - name: Production Build
        paths:
          - dist/**
          - build/**

Artifact Configuration Fields

Required Fields (Structured Syntax Only)

When using the structured syntax, these fields are required:

フィールド	説明
`name`	Display label in UI
`paths`	Glob patterns for file inclusion

Optional Fields

フィールド	説明	既定
`type`	Artifact classification (`shared`, `scoped`, `test-report`)	`shared`
`ignore-paths`	Exclusion patterns	なし
`depth`	Directory search depth	無制限
`capture-on`	When to upload (`success`, `failed`, `always`)	`success`

高度な構成

Exclude Files

- step:
    artifacts:
      - name: Build Output
        paths:
          - dist/**
        ignore-paths:
          - dist/**/*.map
          - dist/**/*.log
    script:
      - npm run build

Limit Search Depth

- step:
    artifacts:
      - name: Top Level Only
        paths:
          - build/**
        depth: 1
    script:
      - make build

Capture on Failure

- step:
    name: Test with Screenshots
    artifacts:
      - name: Failure Screenshots
        type: scoped
        paths:
          - screenshots/**
        capture-on: failed
    script:
      - npm test

Always Capture

- step:
    name: Test and Report
    artifacts:
      - name: Test Results
        paths:
          - test-results/**
          - coverage/**
        capture-on: always
    script:
      - npm test || true

Download Control

Configure artifact retrieval using the download field:

Download All Artifacts (Default)

- step:
    name: Deploy
    script:
      - ./deploy.sh

Skip All Artifacts

- step:
    name: Lint
    download: false
    script:
      - npm run lint

Download Specific Artifacts

pipelines:
  default:
    - step:
        name: Build Frontend
        artifacts:
          - name: Frontend Build
            paths:
              - frontend/dist/**
        script:
          - cd frontend && npm run build
    - step:
        name: Build Backend
        artifacts:
          - name: Backend Build
            paths:
              - backend/build/**
        script:
          - cd backend && make build
    - step:
        name: Deploy Frontend Only
        download:
          - Frontend Build
        script:
          - aws s3 sync frontend/dist/ s3://my-bucket/

File Permissions

Downloaded artifacts receive default permissions of 644 (-rw-r--r--).

To make files executable:

- step:
    name: Deploy with Executable
    script:
      - chmod +x deploy.sh
      - ./deploy.sh

Common Use Cases

Build and Deploy

pipelines:
  branches:
    main:
      - step:
          name: Build
          caches:
            - node
          artifacts:
            - dist/**
          script:
            - npm install
            - npm run build
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - aws s3 sync dist/ s3://production-bucket/

Multi-Stage Build

pipelines:
  default:
    - step:
        name: Compile
        artifacts:
          - name: Compiled Code
            paths:
              - build/**
        script:
          - make compile
    - step:
        name: Test
        artifacts:
          - name: Test Results
            type: scoped
            paths:
              - test-results/**
        script:
          - make test
    - step:
        name: Package
        download:
          - Compiled Code
        artifacts:
          - name: Package
            paths:
              - dist/*.tar.gz
        script:
          - make package

Parallel Builds

pipelines:
  default:
    - parallel:
        - step:
            name: Build Frontend
            artifacts:
              - name: Frontend
                paths:
                  - frontend/dist/**
            script:
              - cd frontend && npm run build
        - step:
            name: Build Backend
            artifacts:
              - name: Backend
                paths:
                  - backend/build/**
            script:
              - cd backend && make build
    - step:
        name: Deploy All
        download:
          - Frontend
          - Backend
        script:
          - ./deploy-all.sh

Test Reports and Screenshots

pipelines:
  default:
    - step:
        name: E2E Tests
        artifacts:
          - name: Test Results
            type: test-report
            paths:
              - test-results/*.xml
          - name: Failure Artifacts
            type: scoped
            paths:
              - screenshots/**
              - videos/**
            capture-on: failed
        script:
          - npm run test:e2e

Artifacts vs Caches

機能	アーティファクト	キャッシュ
目的	Share build outputs	Speed up builds
Retention	14 days	7 days
Size Limit	1 GB	1 GB
範囲	Current pipeline	All pipelines
When Created	After step completes	After successful step
Best For	Compiled code, packages	Dependencies, node_modules

Cross-Pipeline Artifacts

Artifacts can be passed between parent and child pipelines using artifacts: input: and artifacts: output: on a type: pipeline step. This extends the standard artifact model across pipeline boundaries.

# Parent passes its build artifact into a child, receives a report back
- step:
    name: Security Scan
    type: pipeline
    custom: security-scan
    artifacts:
      input:
        - app.tar.gz            # parent artifact pushed into child
      output:
        - security-report.json  # child artifact pulled back to parent

All the same artifact types (shared, scoped, test-report) and configurations (capture-on, ignore-paths, etc.) work the same way within the child pipeline. The parent simply defines which artifacts cross the boundary.

See the Pass artifacts as inputs and outputs across pipelines for full details and examples.

External Artifact Storage

For longer retention or larger files, use external storage:

AWS S3

- step:
    name: Upload to S3
    artifacts:
      - dist/**
    script:
      - npm run build
      - aws s3 sync dist/ s3://my-artifacts-bucket/$BITBUCKET_BUILD_NUMBER/

JFrog Artifactory

- step:
    name: Publish to Artifactory
    script:
      - npm run build
      - curl -u$ARTIFACTORY_USER:$ARTIFACTORY_PASSWORD -T dist/app.zip "https://artifactory.example.com/repo/app-$BITBUCKET_BUILD_NUMBER.zip"

Google Cloud Storage

- step:
    name: Upload to GCS
    script:
      - npm run build
      - gsutil -m cp -r dist/ gs://my-artifacts-bucket/$BITBUCKET_BUILD_NUMBER/

Best Practices

Only artifact what you need - Smaller artifacts upload and download faster
Use specific patterns - dist/**/*.js is better than **/*
Leverage ignore-paths - Exclude unnecessary files
Name artifacts clearly - Descriptive names help with debugging
Consider external storage - For files larger than 1GB or long-term retention
Use scoped for logs - Test reports and screenshots don't need to be shared
Set capture-on appropriately - Only capture failure artifacts when tests fail

Debugging Artifacts

If artifacts aren't working:

Verify paths exist - Files must be created before step completes
Check size - Must be under 1GB
Review patterns - Ensure glob patterns match your files
Check logs - Look for artifact upload messages
Test patterns locally - Use ls dist/** to verify matches

次のステップ

Learn about Caching to speed up builds
Configure Deployments to use artifacts
Set up Service Containers for testing
Pass artifacts across pipeline boundaries with Pipelines: Artifacts Input/Output

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問