@667/ghost-storage-github

Ghost Storage GitHub

This project is a custom storage adapter for Ghost that allows you to use GitHub (a completely free solution) as a storage backend.

Inspiration

This project was inspired by ifvictr/ghost-storage-github. However, due to that project appearing to be abandoned (last update by the author 3 years ago) and no other solutions existing for using GitHub as a storage backend, this project was completely rewritten.

Features

• GitHub as Storage Backend: Seamlessly integrate Ghost with GitHub to store your content.
• Image Transcoding: Supports automatic image transcoding, optimizing images for different use cases, particularly quicker images being served for your blog (images are transcoded to webp by default)
• Reuse Duplicate Files: If a file has the same filename AND the same hash then the current link to that image will be returned instead of being uploaded under another filename. Only if the hash is different will the file be uploaded under a different name. This is to avoid duplicating files on the backend.

Configuration

Example Docker Swarm/Compose partial config:

    environment:
      storage__active: github
      storage__github__token: <your GitHub Personal Access Token here>
      storage__github__owner: <your GitHub user here>
      storage__github__repo: <your GitHub repo here>
      GHOST_STORAGE_GITHUB_TOKEN: <your GitHub Personal Access Token here>
      GHOST_STORAGE_GITHUB_OWNER: <your GitHub user here>
      GHOST_STORAGE_GITHUB_REPO: <your GitHub repo here>
    volumes:
      - type: bind
        source: content
        target: /var/lib/ghost/content
    command: ["/var/lib/ghost/content/copy-storage-adapter.sh", "docker-entrypoint.sh", "node", "current/index.js"]

Note that either the GHOST_STORAGE_GITHUB_ or storage__github__ way of configuring this storage plugin works, while the former overrides the latter.

As well, the plugin code is found in the docker image's content directory so if you also mount that image (thus making the contents unavailable otherwise) the copy-storage-adapter.sh script does exactly that.

Here's a comprehensive list of configurations:

Name	Required?	Description	Environment variable (prefixed with GHOST_STORAGE_GITHUB_)
token	yes	GitHub Personal access token https://github.com/settings/tokens	GHOST_STORAGE_GITHUB_TOKEN
owner	yes	Username of the user/organization the repo is under	GHOST_STORAGE_GITHUB_OWNER
repo	yes	Name of the repo	GHOST_STORAGE_GITHUB_REPO
branch	no	Branch to push assets to. Defaults to main	GHOST_STORAGE_GITHUB_BRANCH
destination	no	Directory to push assets to. Defaults to /	GHOST_STORAGE_GITHUB_DESTINATION
origin	no	URL Origin of newly saved images. Uses raw.githubusercontent.com by default	GHOST_STORAGE_GITHUB_ORIGIN
useRelativeUrls	no	Whether or not to return relative URLs (i.e. under /content/images) instead of absolute URLs. Might be of use to people who generate and serve a static version of their Ghost blog.	USE_RELATIVE_URLS
imageFormat	no	image format to transcode images to. Uses the sharp npm package under the hood https://www.npmjs.com/package/sharp so the same formats are available (i.e. jpeg, png, webp, gif, jp2, tiff, avif, heif, jxl, raw)	GHOST_STORAGE_GITHUB_IMAGE_FORMAT
etagCacheSize	no	GitHub Personal access token https://github.com/settings/tokens	GHOST_STORAGE_GITHUB_ETAG_CACHE_SIZE

Usage

Once configured, Ghost will use your specified GitHub repository to store images.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

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