feat: implement waitTimeout

README.md

@@ -26,7 +26,7 @@ steps:
 - uses: actions/download-artifact@v3
   with:
     name: my-artifact
-    
+
 - name: Display structure of downloaded files
   run: ls -R
 ```
@@ -40,7 +40,7 @@ steps:
   with:
     name: my-artifact
     path: path/to/artifact
-    
+
 - name: Display structure of downloaded files
   run: ls -R
   working-directory: path/to/artifact
@@ -98,7 +98,7 @@ steps:
 - uses: actions/download-artifact@v3
   with:
     path: path/to/artifacts
-    
+
 - name: Display structure of downloaded files
   run: ls -R
   working-directory: path/to/artifacts
@@ -135,6 +135,45 @@ steps:
 
 > 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 `waitTimeout` (seconds) to instruct the download/artifact 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
+        waitTimeout: 300
+```
+
+> 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`)
+
 # Limitations
 
 ### Permission Loss
@@ -157,7 +196,7 @@ If file permissions and case sensitivity are required, you can `tar` all of your
     uses: actions/upload-artifact@v2
     with:
       name: my-artifact
-      path: my_files.tar    
+      path: my_files.tar
 ```
 
 # @actions/artifact package