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 this action: there is no artifact service to expire them. Set a lifecycle rule on your bucket (for example, expire objects under */artifacts/* after N days) or prune the local directory on a schedule.

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.