buckler

README

⛨ Buckler ⛨

Buckler is Shields as a Service (ShaaS, or alternatively, Badges as a Service) for use in GitHub READMEs, or anywhere else. Use buckler with your favorite continuous integration tool, performance monitoring service API, or ridiculous in-joke to surface information.

Buckler is available hosted at b.repl.ca. You may use the API to generate shields at runtime, pregenerate them and host them on your own service, or run your own copy of Buckler to protect important company secrets.

API

Buckler tries to make creating shields easy. Each shield request is a url that has three parts:

• subject
• status
• colour

Parts are separated by a hyphen. The request is suffixed by .png and prefixed with the Buckler host and API version, likely b.repl.ca/v1/. Requests will take the form: http://b.repl.ca/v1/$SUBJECT-$STATUS-$COLOR.png

Examples

• http://b.repl.ca/v1/build-passing-brightgreen.png ⇨
• http://b.repl.ca/v1/downloads-3.4K-blue.png ⇨
• http://b.repl.ca/v1/coverage-unknown-lightgrey.png ⇨
• http://b.repl.ca/v1/review-NACKED-red.png ⇨
• http://b.repl.ca/v1/enterprise-ready-ff69b4.png ⇨

Valid Colours

• brightgreen ⇨
• green ⇨
• yellowgreen ⇨
• yellow ⇨
• orange ⇨
• red ⇨
• grey ⇨
• lightgrey ⇨
• blue ⇨

Six digit RGB hexidecimal colour values work as well:

• 804000 -

Grey?

Don't worry; gray and lightgray work too.

Escaping Underscores and Hyphens

Hyphens (-) are used to delimit individual fields in your shield request. To include a literal hyphen, use two hyphens (--):

http://b.repl.ca/v1/really--cool-status-yellow.png ⇨

Similarly, underscores (_) are used to indicated spaces. To include a literal underscore, use two underscores (__):

http://b.repl.ca/v1/__private-method_name-lightgrey.png ⇨

URL Safe

Buckler API requests are just HTTP GETs, so remember to URL encode!

http://b.repl.ca/v1/uptime-99.99%25-yellowgreen.png ⇨

Try It Out

Play around with the simple form on b.repl.ca

Installing

go get github.com/jbowes/buckler

Alternatively, git clone and go build to run from source.

Command Line

Buckler also provides a command line interface:

# writes to build-passing-brightgreen.png
./buckler -v build -s passing -c brightgreen

# writes to my-custom-filename.png
./buckler -v build -s passing -c green my-custom-filename.png

# writes to standard out
./buckler -v license -s MIT -c blue -

# writes 2 shields
./buckler build-passing-brightgreen.png license-MIT-blue.png

Thanks

• Olivier Lacan for the shields repo
• Steve Matteson for Open Sans