drone-cache

A Drone plugin for caching current workspace files between builds to reduce your build times. drone-cache is a small CLI program, written in Go without any external OS dependencies (such as tar, etc).

With drone-cache, you can provide your own cache key templates, specify archive format (tar, tar.gz, etc) and you can use popular object storage as storage for your cached files, even better you can implement your custom storage backend to cover your use case.

For detailed usage information and a list of available options please take a look at usage and examples. If you want to learn more about custom cache keys, see cache key templates.

If you want to learn more about the story behind drone-cache, you can read our blogpost Making Drone Builds 10 Times Faster!!

Supported Storage Backends

AWS S3
- Configuration
- Example
- Other AWS API compatible stores:
  - Minio
  - Red Hat Ceph
  - IBM Object Store
  - and many many others
Azure Storage
- Configuration
- Example
Google Cloud Storage
- Configuration
- Example
or any mounted local volume
- Configuration
- Example

How does it work

drone-cache stores mounted directories and files under a key at the specified backend (by default S3).

Use this plugin to cache data that makes your builds faster. In the case of a cache miss or an empty cache restore it will fail silently in won't break your running pipeline.

The best example would be to use this with your package managers such as Mix, Bundler or Maven. After your initial download, you can build a cache and then you can restore that cache in your next build.

With restored dependencies from a cache, commands like mix deps.get will only need to download new dependencies, rather than re-download every package on each build.

Example Usage of drone-cache

The following example configuration file (.drone.yml) shows the most common use of drone-cache.

Simple (with AWS S3 backend)

kind: pipeline
name: default

steps:
  - name: restore-cache
    image: meltwater/drone-cache
    environment:
      AWS_ACCESS_KEY_ID:
        from_secret: aws_access_key_id
      AWS_SECRET_ACCESS_KEY:
        from_secret: aws_secret_access_key
    pull: true
    settings:
      restore: true
      cache_key: '{{ .Commit.Branch }}-{{ checksum "go.mod" }}' # default if ommitted is {{ .Commit.Branch }}
      bucket: drone-cache-bucket
      region: eu-west-1
      mount:
        - 'vendor'

  - name: build
    image: golang:1.18.4
    pull: true
    commands:
      - make drone-cache

  - name: rebuild-cache
    image: meltwater/drone-cache
    pull: true
    environment:
      AWS_ACCESS_KEY_ID:
        from_secret: aws_access_key_id
      AWS_SECRET_ACCESS_KEY:
        from_secret: aws_secret_access_key
    settings:
      rebuild: true
      cache_key: '{{ .Commit.Branch }}-{{ checksum "go.mod" }}' # default if ommitted is {{ .Commit.Branch }}
      bucket: drone-cache-bucket
      region: eu-west-1
      mount:
        - 'vendor'

More Examples

examples for Drone, see docs/examples/drone-1.0.md

Usage

Using executable (with CLI args)

Using Docker (with Environment variables)

$ docker run --rm \
      -v "$(pwd)":/app \
      -e DRONE_REPO=octocat/hello-world \
      -e DRONE_REPO_BRANCH=master \
      -e DRONE_COMMIT_BRANCH=master \
      -e PLUGIN_MOUNT=/app/node_modules \
      -e PLUGIN_RESTORE=false \
      -e PLUGIN_REBUILD=true \
      -e PLUGIN_BUCKET=<bucket> \
      -e AWS_ACCESS_KEY_ID=<token> \
      -e AWS_SECRET_ACCESS_KEY=<secret> \
      meltwater/drone-cache

Development

Releases

Release management handled by the CI pipeline. When you create a tag on master branch, CI handles the rest.

You can find released artifacts (binaries, code, archives) under releases.

You can find released images at DockerHub.

PLEASE DO NOT INTRODUCE BREAKING CHANGES

Keep in mind that users usually use the image tagged with latest in their pipeline, please make sure you do not interfere with their working workflow. Latest stable releases will be tagged with the latest.

Versioning

drone-cache uses SemVer for versioning. For the versions available, see the tags on this repository.

As the versioning scheme dictates, drone-cache respects backward compatibility within the major versions. However, the project only offers guarantees regarding the command-line interface (flags and environment variables). Any exported public package can change its API.

Authors and Acknowledgement

See the list of all contributors.

@kakkoyun - Thank you Kemal for bringing drone-cache to life, and building most of the initial version.
@AdamGlazerMW - Special thanks to Adam for the amazing artwork!
@dim - Thanks for the original work that inspired drone-cache!

Inspiration

github.com/bsm/drone-s3-cache (original work)
github.com/Drillster/drone-volume-cache
github.com/drone/drone-cache-lib

Contributing

Please read CONTRIBUTING.md to understand how to submit pull requests to us, and also see our code of conduct.

Future work

All ideas for new features and bug reports will be kept in github.com/meltwater/drone-cache/issues.

One bigger area of future investment is to add a couple of new storage backends for caching the workspace files.

License and Copyright

This project is licensed under the Apache License 2.0.

raphendyr/drone-cache