# Workflow Artifacts

import { Aside } from '@astrojs/starlight/components';

<Aside type="note" title="Release preparation">
The artifact actions are not released yet. These examples require the published
`@v1` actions, updated Avrea runners, and artifact storage enabled for your
organization. The existing GitHub artifact actions remain available.
</Aside>

Avrea artifact actions store build outputs in Avrea. Use them in GitHub Actions
jobs running on Avrea runners or in native Avrea CI workflows. Artifacts appear
in the Avrea console and API; GitHub's artifact list continues to show artifacts
uploaded with GitHub's own actions.

## Upload and download

```yaml
jobs:
  build:
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: mkdir -p output && echo hello > output/result.txt
      - uses: avrea-com/upload-artifact@v1
        with:
          name: build-output
          path: output/
          retention-days: 7

  consume:
    needs: build
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: avrea-com/download-artifact@v1
        with:
          name: build-output
          path: downloaded/
      - run: cat downloaded/result.txt
```

The same action manifests and installed binary serve Linux, macOS and Windows
runners. These actions require Avrea runners; they do not download a binary or
work on GitHub-hosted runners.

## Selecting artifacts

Downloads default to the current run. Set `run-id` to an Avrea run ID or a numeric
GitHub run ID to read another run in the same repository. Cross-repository
downloads are not supported, and `github-token` does not grant extra access.
Downloads require authentication and the source artifact must be in Avrea.

Select by `name`, a glob `pattern`, or Avrea IDs in `artifact-ids`. Run downloads
select the latest available artifact for each name. Without a name, artifacts
use separate directories unless `merge-multiple: true` is set.

## Retention and transfer behavior

Retention defaults to 90 days; `retention-days: 0` uses the organization default.
Requests above 90 days are clamped with a warning. Storage-budget warnings do
not stop uploads. Other upload errors fail the step, and download digest
mismatches fail by default.

Hidden files are excluded unless `include-hidden-files: true` is set. For large,
already compressed files, use `compression-level: 0`. `archive: false` uploads
one file unchanged and uses its basename as the artifact name.

The upload outputs are `artifact-id`, `artifact-url` and `artifact-digest`.
The URL opens the Avrea console and requires authentication. Download actions
return the destination in `download-path`.

## Containers

Native Avrea CI mounts the actions binary read-only into Linux job containers
and Docker actions. GitHub Actions container jobs on Avrea runners require an
explicit read-only mount of `/opt/avrea/bin` at the same container path, or a
mounted binary selected by `AVREA_ACTIONS_BIN`.

## Cache actions

`avrea-com/cache@v1`, `avrea-com/cache/restore@v1` and
`avrea-com/cache/save@v1` use the preinstalled Avrea binary. The combined action
saves only after a successful job; cache-save errors warn and continue.
Standalone save steps follow their workflow condition.

Existing `actions/cache` and setup-action caching continue to work on Avrea
runners. See [GitHub Actions Cache](/cache/github-actions/) for their behavior.