Total Pageviews

Thursday, 11 August 2016


Verify links in awesome projects

Build Status Tests Gem Version
awesome_bot checks for valid URLs in a file, it can be used to verify pull requests updating a README.


$ gem install awesome_bot


Command Line

Usage: awesome_bot [file or files]
       awesome_bot [options]
    -f, --files [files]              Comma separated files to check
    -a, --allow [errors]             Status code errors to allow
        --allow-dupe                 Duplicate URLs are allowed
        --allow-ssl                  SSL errors are allowed
        --allow-redirect             Redirected URLs are allowed
        --allow-timeout              URLs that time out are allowed
    -t, --set-timeout [seconds]      Set connection timeout
    -w, --white-list [urls]          Comma separated URLs to white list
  • You can check multiple files (comma separated or * pattern, look below for details).
  • By default, duplicate URLs or any status code other than 200 are flagged as failures.
    • Use option --allow-dupe to allow duplicates.
    • Use option --allow-redirect to allow redirects.
    • Use option --allow to allow specific status code errors.
    • Use option --white-list (-w for short) to prevent links from being flagged: -w, white lists and all links matching


$ awesome_bot
> Checking links in
Links found: 56, 37 unique
# ...
  Checking URLs: ✓✓✓→?✓→✓→→✓✓→✓✓✓→✓✓✓✓✓✓✓✓✓✓✓→✓✓✓✓✓→✓✓

Issues :-(
> Links
  1. [L007] 301 →
  2. [L008] 302 →
# ...
> Dupes
  1. [L03]
  2. [L05]
# ...
$ awesome_bot --allow-dupe --allow-redirect -w rubydoc,giphy
# allow redirects, dupes and white list all links matching rubydoc and giphy

$ awesome_bot,
# check links in 2 files

$ awesome_bot docs/*.md
# check all markdown files in docs/ directory

$ awesome_bot --allow-timeout -t 5
# speed up validation by setting a timeout of 5s per link request and allowing timeouts

$ awesome_bot --allow 403,429
# allow status code errors 403 and 429
# --allow 301 would be similar to --allow-redirect
(master) $ git branch
* master
(master) $ git checkout -b new-branch
Switched to a new branch 'new-branch'
(new-branch) $ touch && echo '' >>
(new-branch) $ git add
(new-branch) $ git commit -m 'Testing'
[new-branch ef47336] Testing
 1 file changed, 1 insertion(+)
 create mode 100644
(new-branch) $ git diff master.. --name-only | grep '.md' | xargs awesome_bot
> Checking links in
Links to check: 1
Checking URLs: ✓
No issues :-)

Wrote results to


irb(main):001:0> require 'awesome_bot'
=> true
irb(main):002:0> content = ''
=> "..."
irb(main):003:0> result = AwesomeBot.check content
=> #<AwesomeBot::Result:0x007fdde39f4408 @links=...>
# AwesomeBot Result with success, statuses_issues, dupes and more
irb(main):004:0> puts result.success ? 'No errors' : ':-('
More information at rubydoc.

Validate Pull Requests

Does your GitHub README contain a lot of links? awesome_bot can help you validate them when a pull request is created (or a commit is pushed). It is used by:
and more.
  • Use the keyword [ci skip] in your commit title/message to skip verification.
  • Use Danger.

Travis CI

To use awesome_bot with Travis CI, connect your repo and create a .travis.yml file.
language: ruby
rvm: 2.2
before_script: gem install awesome_bot
script: awesome_bot
To turn off email notifications, add the lines below
  email: false

Circle CI

If you prefer Circle CI, it'll work too. Connect your repo and create a circle.yml file.
    version: 2.2.0
    - gem install awesome_bot
    - awesome_bot


Circle CI, Codeship, and Semaphore CI support running tests without adding a file to the repo (a public configuration file can however help others contribute).
# Codeship
rvm use 2.2.0 --install
gem install awesome_bot

# Semaphore CI
Language: Ruby
Ruby version: 2.2
Databases for: don't generate
gem install awesome_bot

Status Badge

Build Status
To add the Travis CI build status badge above to your project, use the following code
[![Build Status](<username>/<project>.svg)](<username>/<project>)

[![Build Status](](
As it happens, the default code snippet provided contain a redirect so adding a badge could fail your status :sob:.. one way to fix this is to white list travis-ci, i.e.
- awesome_bot --white-list travis-ci
You can also add a badge for other CI tools, check out


Integrate awesome_bot with Danger and have results reported back to the pull request).
Here's the step in your Dangerfile:
# Check links
require 'json'
results = ''
j = JSON.parse results
if j['error']==true
  fail j['title']
  markdown j['message']