DigitalOcean Spaces Action

Upload directories/files to DigitalOcean Spaces via GitHub Actions.

👋 Introduction

Use 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 can also automatically grab the version number from the package.json and use it to host multiple versions at once (more info below).

⭐ Features

Upload a single file or whole directories
Specify output directory on your Space
Automatic versioning of your uploads
Use your CDN endpoint (custom domain)
Integrates with GitHub deployments

📚 Usage

Create a .yml file in your .github/workflows folder (you can find more info about the structure in the GitHub Docs):

.github/workflows/upload.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.

Action Versioning

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

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):

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 takes:

Key	Value	Required	Default
`access_key`	Your DigitalOcean access key - more info	Yes	N/A
`secret_key`	Your DigitalOcean secret key - more info	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	Yes	N/A
`out_dir`	Path to the output directory in your Space (where you want to upload to) - more info	No	`/`
`versioning`	Enable versioning (either set it to true or specify path to package.json) - more info	No	`false`
`cdn_domain`	Custom domain pointing to your CDN endpoint - more info	No	N/A
`permission`	Access permissions of the uploaded files - more info	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. The space_name and space_region are different based on your created Space.

It is recommended to set them as Repository Secrets.

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

Output directory

By default 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

Versioning

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

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 will just use it when logging it and assigning it to the action output variable output_url.

See example

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.

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.

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.

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.

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

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 can be perfectly intergrated with Actions like Create Deployment Status Update to create a deployment once all files are uploaded:

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:

📝 To do

Here is what's currently planned for 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!

💻 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) in my free time. If you want to support me:

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.