GitHub Actions Tutorial — Upload Artifacts

Upload Artifacts

Artifacts are files produced during a workflow run — build outputs, test reports, logs, binaries. The actions/upload-artifact action saves these files so they can be downloaded later by other jobs or by users.

---

Basic Upload

steps:
  - uses: actions/checkout@v4
  - run: npm ci && npm run build

  - name: Upload build output
    uses: actions/upload-artifact@v4
    with:
      name: build-dist          # artifact name
      path: ./dist              # files to upload

After the workflow, the artifact appears in the Actions UI under the run’s “Artifacts” section.

---

Upload Options

- uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: |
      ./dist
      ./reports/*.html
      !./dist/debug             # exclude pattern
    retention-days: 7           # default: 90
    if-no-files-found: error    # error, warn (default), or ignore
    compression-level: 6        # 0 (none) to 9 (max), default 6
    overwrite: true             # overwrite existing artifact with same name

Option	Default	Purpose
name	Required	Artifact display name
path	Required	Files or directories to upload
retention-days	90	Days before auto-deletion
if-no-files-found	warn	Behavior when no files match
compression-level	6	gzip compression level
overwrite	false	Replace existing artifact

---

Upload Multiple Artifacts

steps:
  - run: npm test

  - name: Upload test report
    uses: actions/upload-artifact@v4
    with:
      name: test-report
      path: ./test-results/

  - name: Upload coverage
    uses: actions/upload-artifact@v4
    with:
      name: coverage-report
      path: ./coverage/

Each name creates a separate artifact in the UI.

---

Upload on Failure

Upload test logs or screenshots when tests fail:

steps:
  - run: npm test

  - name: Upload failure logs
    if: failure()
    uses: actions/upload-artifact@v4
    with:
      name: failure-logs
      path: |
        ./logs/
        ./screenshots/

---

Artifact Limits

Limit	Value
Max size per artifact	10 GB
Max total per repo	Depends on plan
Default retention	90 days
Max retention	400 days

Free plan: 500 MB storage, 1 GB for Pro accounts.

---

Common Mistakes

Mistake	Fix
Artifact empty	Check the path: value — it’s relative to $GITHUB_WORKSPACE
Upload fails silently	Set if-no-files-found: error to fail on missing files
Artifact too large	Use compression-level: 9 or exclude unnecessary files
Wrong artifact name	Names must be unique per workflow run (v4 enforces this)

---

Quick Reference

Concept	Syntax
Upload	uses: actions/upload-artifact@v4
Required	name: and path:
Multi-path	Use \| for multiple paths
Exclude	Prefix with !
Retention	retention-days: N
On failure	if: failure() before upload

---

← Back to: Chapter 8: Artifacts & Caching

Next: Download Artifacts →