upload-artifact-action

Upload named build artifacts on Forgejo Actions runners to storage you control (S3-compatible or a directory), with no dependency on the GitHub artifact API or github.com. A drop-in port of actions/upload-artifact.

Pairs with rasterstate/download-artifact-action, which reads what this writes. The storage layer (S3 SigV4, multipart, filesystem) is shared with rasterstate/cache-action.

Quick start

jobs:
  build:
    runs-on: [self-hosted, Linux]
    env:
      RASTER_ARTIFACTS_S3_BUCKET: ci-artifacts
      RASTER_ARTIFACTS_S3_ENDPOINT: https://fsn1.your-objectstorage.com   # omit for AWS
      RASTER_ARTIFACTS_S3_REGION: fsn1
      RASTER_ARTIFACTS_S3_ACCESS_KEY_ID: ${{ secrets.ARTIFACTS_KEY_ID }}
      RASTER_ARTIFACTS_S3_SECRET_ACCESS_KEY: ${{ secrets.ARTIFACTS_SECRET }}
    steps:
      - uses: actions/checkout@v6
      - run: make build
      - uses: https://rasterhub.com/rasterstate/upload-artifact-action@v1
        with:
          name: dist
          path: |
            build/**
            !build/**/*.map

Filesystem backend (shared mount across runners):

    env:
      RASTER_ARTIFACTS_LOCAL_DIR: /mnt/ci-artifacts

Inputs

Mirror actions/upload-artifact@v4.

Input	Required	Default	Description
name	no	artifact	Artifact name.
path	yes		Files, directories, and globs, one per line. Supports **, *, ~, and ! negation.
if-no-files-found	no	warn	warn, error, or ignore.
retention-days	no		Recorded in metadata; expiry is your storage's job (see below).
compression-level	no		Accepted for compatibility; informational.
overwrite	no	false	Replace an existing artifact of the same name for this run.
include-hidden-files	no	false	Include dotfiles.

Outputs

Output	Description
artifact-id	Stable id (sha256 of repository/run/name, truncated).
artifact-url	Storage locator for the uploaded object.
artifact-digest	sha256: digest of the archive.

Storage layout

<prefix>/<repo>/artifacts/<run-id>/<name>.tar.<zst|gz>
<prefix>/<repo>/artifacts/<run-id>/<name>.meta.json

Artifacts are scoped per repository ($GITHUB_REPOSITORY) and per run ($GITHUB_RUN_ID), read from the Forgejo environment. The metadata sidecar lets the download action find the artifact by name and know how it was compressed.

Backend configuration

All from the environment, namespaced RASTER_ARTIFACTS_*. The S3 knobs match cache-action's RASTER_CACHE_S3_* set (endpoint, region, prefix, force-path-style, use-ssl, part size, conditional write, segment size), so you can point artifacts and cache at the same bucket with different prefixes.

Variable	Notes
RASTER_ARTIFACTS_BACKEND	s3 or local; auto-detected.
RASTER_ARTIFACTS_S3_BUCKET	Required for S3.
RASTER_ARTIFACTS_S3_ENDPOINT	Omit for AWS; set for R2/MinIO/Hetzner.
RASTER_ARTIFACTS_S3_REGION	Default us-east-1 (auto for R2).
RASTER_ARTIFACTS_S3_ACCESS_KEY_ID / _SECRET_ACCESS_KEY	Fall back to AWS_*.
RASTER_ARTIFACTS_S3_PREFIX	Key prefix inside the bucket.
RASTER_ARTIFACTS_LOCAL_DIR	Directory for the filesystem backend.
RASTER_ARTIFACTS_SCOPE	Override the per-repo isolation prefix.
RASTER_ARTIFACTS_COMPRESSION	zstd, gzip, or none.

See cache-action's README for the full S3 tuning table; the same names apply with the RASTER_ARTIFACTS_ prefix.

Retention

retention-days is recorded in the artifact metadata but not enforced by the upload step: there is no artifact service to expire it. On S3, the simplest option is still a bucket lifecycle rule (for example, expire objects under */artifacts/* after N days).

When you cannot rely on a lifecycle rule (a local directory, or a bucket without one), run the bundled prune utility on a schedule. It scans the artifacts subtree, reads each .meta.json, computes age from the recorded createdAt, and deletes the archive plus its sidecar once retention-days has elapsed:

# Same RASTER_ARTIFACTS_* env as the upload step. Set the repo scope explicitly
# when running outside a job (GITHUB_REPOSITORY is normally present in Actions).
export RASTER_ARTIFACTS_LOCAL_DIR=/mnt/ci-artifacts
export GITHUB_REPOSITORY=rasterstate/upload-artifact-action   # or RASTER_ARTIFACTS_SCOPE

node src/prune.js --dry-run   # report what would be deleted, change nothing
node src/prune.js             # delete expired artifacts

It is deliberately conservative:

• Only entries whose recorded retention window has actually elapsed are deleted.
• Artifacts with no retention-days record are left alone. To expire those too, pass --force --max-age=<days>; that window is the fallback retention applied only to record-less artifacts.
• Entries without a usable createdAt timestamp are skipped (no safe way to compute age).

The utility reads the same backend and scope from the environment, so point it at the bucket (or directory) you upload to. It prunes one repo scope per run.

Examples

See examples/workflows: build artifacts, test reports, release binaries, and a multi-job upload/download flow.

Migrating from actions/upload-artifact

See MIGRATION.md. Change the uses: line and add backend env:; the with: block is unchanged.

License

MIT. See LICENSE.