Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/betahuhn/do-spaces-action

📦Upload directories/files to DigitalOcean Spaces via GitHub Actions. Supports package/library versioning.
https://github.com/betahuhn/do-spaces-action

actions cdn digitalocean digitalocean-spaces github spaces

Last synced: 9 days ago
JSON representation

📦Upload directories/files to DigitalOcean Spaces via GitHub Actions. Supports package/library versioning.

Awesome Lists containing this project

README 

        


  

# DigitalOcean Spaces Action



[![Build](https://github.com/BetaHuhn/do-spaces-action/workflows/Build/badge.svg)](https://github.com/BetaHuhn/do-spaces-action/actions?query=workflow%3ABuild) [![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/BetaHuhn/do-spaces-action/blob/master/LICENSE) ![David](https://img.shields.io/david/betahuhn/do-spaces-action)



Upload directories/files to DigitalOcean Spaces via GitHub Actions.






## 👋 Introduction



Use [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) to deploy a file or directory to your DigitalOcean Space with GitHub Actions. This can be used to host your static site, or as an self-hosted alternative to something like JSDelivr for serving your JS files/library via a CDN. [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) can also automatically grab the version number from the package.json and use it to host multiple versions at once (more info [below](#versioning)).



## ⭐ Features



- Upload a [single file](#single-file-upload) or [whole directories](#basic-example)

- Specify [output directory](#output-directory) on your Space

- Automatic [versioning](#versioning) of your uploads

- Use your [CDN endpoint](#cdn-domain) (custom domain)

- Integrates with [GitHub deployments](#create-deployment-on-github)



## 📚 Usage



Create a `.yml` file in your `.github/workflows` folder (you can find more info about the structure in the [GitHub Docs](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions)):



**.github/workflows/upload.yml**



```yml

name: Upload to DO Spaces

on:

  push:

    branches:

      - main

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout Repository

        uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: src

```



More info on how to specify what files to upload where [below](#%EF%B8%8F-action-inputs).



### Action Versioning



To always use the latest version of the action add the `latest` tag to the action name like this:



```yml

uses: BetaHuhn/do-spaces-action@latest

```



If you want to make sure that your workflow doesn't suddenly break when a new major version is released, use the `v2` tag instead (recommended usage):



```yml

uses: BetaHuhn/do-spaces-action@v2

```



With the `v2` tag you will always get the latest non-breaking version which will include potential bug fixes in the future. If you use a specific version, make sure to regularly check if a new version is available, or enable Dependabot.



## ⚙️ Action Inputs



Here are all the inputs [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) takes:



| Key | Value | Required | Default |

| ------------- | ------------- | ------------- | ------------- |

| `access_key` | Your DigitalOcean access key - [more info](#authentication) | **Yes** | N/A |

| `secret_key` | Your DigitalOcean secret key - [more info](#authentication) | **Yes** | N/A |

| `space_name` | The name of your DigitalOcean Space | **Yes** | N/A |

| `space_region` | The region of your DigitalOcean Space | **Yes** | N/A |

| `source` | Path to the source file or folder (what you want to upload) - [more info](#source) | **Yes** | N/A |

| `out_dir` | Path to the output directory in your Space (where you want to upload to) - [more info](#output-directory) | **No** | `/` |

| `versioning` | Enable versioning (either set it to true or specify path to package.json) - [more info](#versioning) | **No** | `false` |

| `cdn_domain` | Custom domain pointing to your CDN endpoint - [more info](#cdn-domain) | **No** | N/A |

| `permission` | Access permissions of the uploaded files - [more info](#file-permissions) | **No** | `public-read` |



### Authentication



In order to access your DigitalOcean Space, you have to specify a few required values. The `access_key` and `secret_key` can be generated on your DigitalOcean [Account Page](https://cloud.digitalocean.com/account/api/tokens). The `space_name` and `space_region` are different based on your created Space.



It is recommended to set them as [Repository Secrets](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository).



### Source



The `source` input can either point to a single file or to a whole directory which should be uploaded. The path is relative to the root of your repository.



[See example](#single-file-upload)



### Output directory



By default [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) will upload all files to the root of your Space. You can specify a different output directory with the `out_dir` input.



[See example](#custom-output-path)



### Versioning



[do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) also supports versioning and can detect the current version from your `package.json` and then upload the file/s to a folder with the version as the name. Let's suppose you bump the version of your project from `v2.3.0` to `v2.4.0`. Both versions would remain on your Space, under different paths:



- `v2.3.0` -> `https://SPACE.fra1.digitaloceanspaces.com/js/v2.3.0/index.min.js`

- `v2.4.0` -> `https://SPACE.fra1.digitaloceanspaces.com/js/v2.4.0/index.min.js`



The most recent version will be available with the `latest` tag:



- `latest` -> `https://SPACE.fra1.digitaloceanspaces.com/js/latest/index.min.js`



The `versioning` parameter can be set to true/false, or a string representing the path to the `package.json` file.



[See example](#use-packagejson-version)



### CDN Domain



Instead of outputting the normal DigitalOcean domain `https://SPACE.fra1.digitaloceanspaces.com/`, you can also specify your custom CDN domain with `cdn_domain`.



**Note:** `https://SPACE.REGION.digitaloceanspaces.com/` is still used to connect to your Space, [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) will just use it when logging it and assigning it to the action output variable `output_url`.



[See example](#specify-a-custom-cdn-domain)



### File permissions



By default all uploaded files have their access permission set to `public-read`. This means that anyone can access them via their own Space URL. If you want to block public access, you can set `permission` to `private`.



## 📖 Examples



Here are a few examples to help you get started!



### Basic Example



This example will run everytime you create a new release and then upload all files and directories in the `src` folder to the root of your Space.



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: src

```



### Custom output path



This example will run everytime you create a new release and then upload the `src` directory to the `dist` folder on your Space.



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: src

          out_dir: dist

```



### Single file upload



This example will run everytime you create a new release and then upload the file `path/to/file.js` to the root of your Space.



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: path/to/file.js

```



### Use package.json version



This example will run everytime you create a new release and then upload the file `dist/index.min.js` to both the `latest` and `vX.X.X` folder in the js directory in your Space.



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: dist/index.min.js

          out_dir: js

          versioning: true

```



The `versioning` parameter can be set to true/false, or a string representing the path to the `package.json` file.



### Specify a custom CDN domain



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: BetaHuhn/do-spaces-action@v2

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: src

          cdn_domain: cdn.example.com

```



### Create deployment on GitHub



[do-spaces-action](https://github.com/BetaHuhn/do-spaces-action) can be perfectly intergrated with Actions like [Create Deployment Status Update](https://github.com/marketplace/actions/create-deployment-status-update) to create a deployment once all files are uploaded:



```yml

name: Upload to DO Spaces

on:

  release:

    types: [created]

jobs:

  upload:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@master

      - uses: altinukshini/deployment-action@releases/v1

        name: start deployment

        id: deployment

        with:

          token: ${{ secrets.GITHUB_TOKEN}}

          description: Uploading files to DO Spaces

          environment: production



      - uses: BetaHuhn/do-spaces-action@v2

        name: upload to spaces

        id: spaces

        with:

          access_key: ${{ secrets.ACCESS_KEY}}

          secret_key: ${{ secrets.SECRET_KEY }}

          space_name: ${{ secrets.SPACE_NAME }}

          space_region: ${{ secrets.SPACE_REGION }}

          source: src

          out_dir: dist

          versioning: true



      - name: update deployment status

        if: always()

        uses: altinukshini/deployment-status@releases/v1

        with:

          token: ${{ secrets.GITHUB_TOKEN }}

          state: ${{ job.status }}

          deployment_id: ${{ steps.deployment.outputs.deployment_id }}

          environment_url: ${{steps.spaces.outputs.output_url}}

          description: "Successfully uploaded files to DO Spaces"

```



Here's how that will look on your Repo:



![Deployment preview](https://cdn.mxis.ch/assets/do-spaces-action/deployment.png)



## 📝 To do



Here is what's currently planned for [do-spaces-action](https://github.com/BetaHuhn/do-spaces-action):



- **Different environments:** add the option to change the upload path pased on the environment (staging/production)



If you have an idea, feel free to [open an issue](https://github.com/BetaHuhn/do-spaces-action/issues/new?labels=feature+request&template=feature_request.md)!



## 💻 Development



Issues and PRs are very welcome!



The actual source code of this library is in the `src` folder.



- run `yarn lint` or `npm run lint` to run eslint.

- run `yarn start` or `npm run start` to run the Action locally.

- run `yarn build` or `npm run build` to produce a production version in the `dist` folder.



## ❔ About



This project was developed by me ([@betahuhn](https://github.com/BetaHuhn)) in my free time. If you want to support me:



[![Donate via PayPal](https://img.shields.io/badge/paypal-donate-009cde.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=394RTSBEEEFEE)



[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F81S2RK)



## 📄 License



Copyright 2021 Maximilian Schiller



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.