Merge pull request #7 from hammerstonedev/af-github-actions

GitHub Actions Driver

Author: aarondfrancis

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Unreleased
 
-- Add Hash command
+- Add `airdrop:hash` command.
+- Add GitHub Actions driver.
 
 ## 0.1.0 - 2021-05-16
 

config/airdrop.php

@@ -1,6 +1,7 @@
 <?php
 
 use Hammerstone\Airdrop\Drivers\FilesystemDriver;
+use Hammerstone\Airdrop\Drivers\GithubActionsDriver;
 use Hammerstone\Airdrop\Triggers\ConfigTrigger;
 use Hammerstone\Airdrop\Triggers\FileTrigger;
 
@@ -24,6 +25,19 @@
             // Used to build up the ZIP file before stashing it.
             'local_tmp_directory' => env('AIRDROP_LOCAL_TMP_DIR', storage_path('framework')),
 
+            // The skip file is an empty file that will be created to
+            // indicate that asset building can be skipped.
+            'skip_file' => env('AIRDROP_SKIP_FILE', base_path('.airdrop_skip')),
+        ],
+
+        'github' => [
+            // Use in conjunction with the Cache step in GitHub Actions.
+            'class' => GithubActionsDriver::class,
+
+            // Make sure this matches the `path` key in the
+            // cache step of your GitHub Actions Workflow.
+            'local_tmp_directory' => env('AIRDROP_LOCAL_TMP_DIR', '/tmp/'),
+
             // The skip file is an empty file that will be created to
             // indicate that asset building can be skipped.
             'skip_file' => env('AIRDROP_SKIP_FILE', base_path('.airdrop_skip')),

docs/drivers/filesystem.md

@@ -1,13 +1,13 @@
 # Filesystem Driver
 
-The Filesystem Driver is the default (and only!) driver that we ship with. It stores all of your built assets as a `.zip` on a filesystem of your choosing. 
+The Filesystem Driver is the default driver that we ship with. It stores all of your built assets as a `.zip` on a filesystem of your choosing. 
 
 
 ## Configuration
 
 If you'd like to change the configuration, you can do so in `airdrop.php`.
 
-config/aidrop.php{.filename}
+config/airdrop.php{.filename}
 ```php
 [
     'drivers' => [

docs/drivers/github.md

@@ -0,0 +1,65 @@
+# GitHub Actions Driver
+
+The GitHub Actions driver works as a part of your GitHub Workflows to cache built assets from run to run, even across branches. 
+
+When using the GitHub driver, there is _no need_ for a remote disk anywhere. Instead, we rely on the [Cache Action](https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows) to cache the built files for us.
+
+## Configuration
+
+The GitHub driver is an extension of the Filesystem driver so much of the configuration is the same, although fewer items are needed. 
+
+config/airdrop.php{.filename}
+```php
+[
+    'drivers' => [
+         'github' => [
+            // Use in conjunction with the Cache step in GitHub Actions.
+            'class' => GithubActionsDriver::class,
+
+            // Make sure this matches the `path` key in the
+            // cache step of your GitHub Actions Workflow.
+            'local_tmp_directory' => env('AIRDROP_LOCAL_TMP_DIR', '/tmp/'),
+
+            // The skip file is an empty file that will be created to
+            // indicate that asset building can be skipped.
+            'skip_file' => env('AIRDROP_SKIP_FILE', base_path('.airdrop_skip')),
+        ]
+    ],
+]
+
+```
+
+`local_tmp_directory` is a place that Airdrop can use to create the `.zip` file before it is uploaded. This needs to match that path that you put in your `[workflow].yml` file.
+
+`skip_file` is the file we referenced in the [deploying](/deploying) section. It's used as a signal to other processes that the built files have been successfully restored, and they do not need to be built again.
+
+## GitHub Workflow Configuration
+
+There are a couple steps you'll need to add to your GitHub Workflow to take advantage of the asset caching.
+
+The first step is to calculate the hash of the inputs and save it in the environment for the cache step to use:
+
+.github/workflows/deploy.yml{.filename}
+```yaml
+- name: Generate Airdrop Hash
+  run: echo "AIRDROP_HASH=$(php artisan airdrop:hash)" >> $GITHUB_ENV
+```
+
+This command is going to run `php artisan airdrop:hash` to calculate the hash of all the inputs, and then it is going to store it as an environment variable named `AIRDROP_HASH`. This allows the cache step to look for the right key.
+
+The next step you'll need to add is the cache step:
+
+.github/workflows/deploy.yml{.filename}
+```yaml
+- name: Generate Airdrop Hash
+  run: echo "AIRDROP_HASH=$(php artisan airdrop:hash)" >> $GITHUB_ENV
+
+- name: Cache Airdrop Assets # [tl! ~~]
+  uses: actions/cache@v2 # [tl! ~~]
+  with: # [tl! ~~]
+    key: ${{ runner.os }}-airdrop-${{ env.AIRDROP_HASH }} # [tl! ~~]
+    path: /tmp/airdrop-* # [tl! ~~]
+```
+
+This step will cache the built zip file from Airdrop, and save it for up to seven days, per GitHub's [usage limits](https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). (Remember that if a cache misses, your app will simply rebuild the assets!)
+ 

docs/manifest.json

@@ -16,6 +16,7 @@
         "Drivers": {
             "children": {
                 "Filesystem": "/drivers/filesystem",
+                "GitHub Actions": "/drivers/github",
                 "Custom": "/drivers/custom"
             }
         },

src/Drivers/FilesystemDriver.php

@@ -37,16 +37,27 @@ public function upload()
 
         $this->makeZip($zipPath);
 
-        $this->output('Uploading to remote disk at ' . $this->remoteStashPath() . $this->stashedPackageFilename());
+        $this->uploadToRemoteStorage($zipPath);
+    }
 
-        $this->disk()->putFileAs(
-            $this->remoteStashPath(),
-            $zipPath,
-            $this->stashedPackageFilename()
-        );
+    /**
+     * Called before building files, to see if we can skip that
+     * altogether and just download them.
+     */
+    public function download()
+    {
+        if ($this->extract()) {
+            $this->output('Assets downloaded and extracted.');
 
-        // Clean up after ourselves once it's uploaded.
-        File::delete($zipPath);
+            // Touch a file that can be used to inform the deploy
+            // process that building assets can be skipped.
+            File::put($this->skipFilePath(), '');
+        } else {
+            $this->output('Assets did not exist.');
+
+            // Remove the file if extraction did not succeed.
+            File::delete($this->skipFilePath());
+        }
     }
 
     /**
@@ -74,24 +85,6 @@ public function makeZip($path)
         $zip->close();
     }
 
-    /**
-     * Called before building files, to see if we can skip that
-     * altogether and just download them.
-     */
-    public function download()
-    {
-        if ($this->extract()) {
-            $this->output('Assets downloaded and extracted.');
-            // Touch a file that can be used to inform the deploy
-            // process that building assets can be skipped.
-            File::put($this->skipFilePath(), '');
-        } else {
-            $this->output('Assets did not exist.');
-            // Remove the file if extraction did not succeed.
-            File::delete($this->skipFilePath());
-        }
-    }
-
     public function extract()
     {
         if (!$this->exists()) {
@@ -100,24 +93,20 @@ public function extract()
 
         $zipPath = $this->localStashPath() . $this->stashedPackageFilename();
 
-        // Download the file to local disk as a stream.
-        File::put(
-            $zipPath,
-            $this->disk()->readStream($this->remoteStashPath() . $this->stashedPackageFilename())
-        );
+        $this->downloadFromRemoteStorage($zipPath);
 
         $zip = new ZipArchive;
 
         $status = $zip->open($zipPath);
 
         if ($status !== true) {
-            throw new Exception('Airdrop was trying to extract previously built assets, but could not open the zip file at ' . json_encode($zipPath));
+            throw new Exception(
+                'Airdrop was trying to extract previously built assets, but could not open the zip file at ' . json_encode($zipPath)
+            );
         }
 
         // Put all the assets back where they should be.
-        $extracted = $zip->extractTo(base_path());
-
-        if (!$extracted) {
+        if (!$zip->extractTo(base_path())) {
             throw new Exception('Zip not extracted');
         }
 
@@ -169,6 +158,36 @@ protected function stashedPackageFilename()
         return "airdrop-{$this->hash}.zip";
     }
 
+    /**
+     * @param string $zipPath
+     * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
+     */
+    protected function downloadFromRemoteStorage($zipPath)
+    {
+        // Download the file to local disk as a stream.
+        File::put(
+            $zipPath,
+            $this->disk()->readStream($this->remoteStashPath() . $this->stashedPackageFilename())
+        );
+    }
+
+    /**
+     * @param string $zipPath
+     */
+    protected function uploadToRemoteStorage($zipPath)
+    {
+        $this->output('Uploading to remote disk at ' . $this->remoteStashPath() . $this->stashedPackageFilename());
+
+        $this->disk()->putFileAs(
+            $this->remoteStashPath(),
+            $zipPath,
+            $this->stashedPackageFilename()
+        );
+
+        // Clean up after ourselves once it's uploaded.
+        File::delete($zipPath);
+    }
+
     /**
      * @return string
      */

src/Drivers/GithubActionsDriver.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * @author Aaron Francis <aarondfrancis@gmail.com|https://twitter.com/aarondfrancis>
+ */
+
+namespace Hammerstone\Airdrop\Drivers;
+
+class GithubActionsDriver extends FilesystemDriver
+{
+    public function exists()
+    {
+        return file_exists($this->localStashPath() . $this->stashedPackageFilename());
+    }
+
+    protected function downloadFromRemoteStorage($zipPath)
+    {
+        // For GitHub actions there is no downloading required.
+        // The file will be placed in the appropriate location
+        // by the Cache step of the workflow.
+    }
+
+    protected function uploadToRemoteStorage($zipPath)
+    {
+        // No upload is required  either. GitHub will take the
+        // zip from the tmp directory and cache it for us for
+        // later use.
+    }
+}