# Download-Artifact v3

This downloads artifacts from your build

See also [upload-artifact](https://github.com/actions/upload-artifact).

# What's new

- Download all artifacts at once
- Output parameter for the download path
- Port entire action to typescript from a runner plugin so it is easier to collaborate and accept contributions

Refer [here](https://github.com/actions/download-artifact/tree/v2) for the previous version

# Usage

See [action.yml](action.yml)

# Download a Single Artifact

Basic (download to the current working directory):
```yaml
steps:
- uses: actions/checkout@v2

- uses: actions/download-artifact@v3
  with:
    name: my-artifact

- name: Display structure of downloaded files
  run: ls -R
```

Download to a specific directory:
```yaml
steps:
- uses: actions/checkout@v2

- uses: actions/download-artifact@v3
  with:
    name: my-artifact
    path: path/to/artifact

- name: Display structure of downloaded files
  run: ls -R
  working-directory: path/to/artifact
```

Basic tilde expansion is supported for the `path` input:
```yaml
  - uses: actions/download-artifact@v3
    with:
      name: my-artifact
      path: ~/download/path
```

## Compatibility between `v1` and `v2`/`v3`

When using `download-artifact@v1`, a directory denoted by the name of the artifact would be created if the `path` input was not provided. All of the contents would be downloaded to this directory.
```
   current/working/directory/
      my-artifact/
          ... contents of my-artifact
```

With `v2` and `v3`, when an artifact is specified by the `name` input, there is no longer an extra directory that is created if the `path` input is not provided. All the contents are downloaded to the current working directory.
```
   current/working/directory/
      ... contents of my-artifact
```

To maintain the same behavior for `v2` and `v3`, you can set the `path` to the name of the artifact so an extra directory gets created.
```
- uses: actions/download-artifact@v2
  with:
    name: my-artifact
    path: my-artifact
```


# Download All Artifacts

If the `name` input parameter is not provided, all artifacts will be downloaded. **To differentiate between downloaded artifacts, a directory denoted by the artifacts name will be created for each individual artifact.**
Example, if there are two artifacts `Artifact-A` and `Artifact-B`, and the directory is `etc/usr/artifacts/`, the directory structure will look like this:
```
  etc/usr/artifacts/
      Artifact-A/
          ... contents of Artifact-A
      Artifact-B/
          ... contents of Artifact-B
```

Download all artifacts to a specific directory
```yaml
steps:
- uses: actions/checkout@v2

- uses: actions/download-artifact@v3
  with:
    path: path/to/artifacts

- name: Display structure of downloaded files
  run: ls -R
  working-directory: path/to/artifacts
```

Download all artifacts to the current working directory
```yaml
steps:
- uses: actions/checkout@v2

- uses: actions/download-artifact@v3

- name: Display structure of downloaded files
  run: ls -R
```

# Download path output

The `download-path` step output contains information regarding where the artifact was downloaded to. This output can be used for a variety of purposes such as logging or as input to other actions. Be aware of the extra directory that is created if downloading all artifacts (no name specified).

```yaml
steps:
- uses: actions/checkout@v2

- uses: actions/download-artifact@v3
  id: download
  with:
    name: 'my-artifact'
    path: path/to/artifacts

- name: 'Echo download path'
  run: echo ${{steps.download.outputs.download-path}}
```

> Note: The `id` defined in the `download/artifact` step must match the `id` defined in the `echo` step (i.e `steps.[ID].outputs.download-path`)

# Waiting for the artifact to be available

You can specify `wait-timeout` (seconds) to instruct the download-artifact action to retry until the artifact is available.
This is useful if you want to launch the job before its dependency job has finished, e.g. if the dependant requires some time-consuming steps.
You can do this by removing the `needs` dependency and relying on the retry logic of download-artifact to fetch the artifact after it's uploaded.

Beware that GitHub actions come with a limited number of runners available, so if your workflow uses up the limt on the "dependant" jobs,
your artifact-source jobs may never be scheduled.

```yaml
jobs:
  producer-job:
    name: This job produces an artifact
    steps:
      # ... do something

      # ... then upload an artifact as usual
      - uses: actions/upload-artifact@v1
        with:
          name: artifact-name
          path: path/to/artifact

  dependant-job:
    name: This job has some long running preparation that can run before the artifact is necessary
    steps:
      # your long-running steps come first - they're run in parallel with the `producer-job` above (given you have enouth GH actions runners available)
      run: # e.g. install some large SDK

      # then when you finally need the artifact to be downloaded
      uses: actions/download-artifact@v2
      with:
        name: artifact-name
        path: output-path
        # wait for 300 seconds
        wait-timeout: 300
```

# Limitations

### Permission Loss

:exclamation: File permissions are not maintained during artifact upload :exclamation: For example, if you make a file executable using `chmod` and then upload that file, post-download the file is no longer guaranteed to be set as an executable.

### Case Insensitive Uploads

:exclamation: File uploads are case insensitive :exclamation: If you upload `A.txt` and `a.txt` with the same root path, only a single file will be saved and available during download.

### Maintaining file permissions and case sensitive files

If file permissions and case sensitivity are required, you can `tar` all of your files together before artifact upload. Post download, the `tar` file will maintain file permissions and case sensitivity.

```yaml
  - name: 'Tar files'
    run: tar -cvf my_files.tar /path/to/my/directory

  - name: 'Upload Artifact'
    uses: actions/upload-artifact@v2
    with:
      name: my-artifact
      path: my_files.tar
```

# @actions/artifact package

Internally the [@actions/artifact](https://github.com/actions/toolkit/tree/main/packages/artifact) NPM package is used to interact with artifacts. You can find additional documentation there along with all the source code related to artifact download.

# License

The scripts and documentation in this project are released under the [MIT License](LICENSE)