Skip to main content

CI Integrations

If you're using GitHub, we strongly encourage you to install our GitHub app. This will provide the best possible experience for everyone involved from the originator of the PR all the way to the reviewer.

For all other CI servers the process is almost exactly the same:

  1. Make sure git is present and configured (user.name and user.email must be set.)
  2. Download the latest 64 bit dynamically-linked executable with curl (Node is no longer needed)
  3. Make the download executable
  4. Return the result of swimm_cli verify, which is nonzero on failure
Make sure you don't use 'shallow' pulls

Shallow pulls are where only part of the history is fetched. This can save a few seconds of time for projects that have extremely long histories, but it can trigger false alarms for Swimm when it can't reconcile specific changes in the code.

Below are tested example configurations that you can use as-is, or as a starting point for your own configuration:

Github Actions

name: Swimm
on: pull_request
jobs:
Verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0 # pulling the commits history is required for the verification to function properly
- uses: actions/setup-node@v2
with:
node-version: '14'
- uses: swimmio/swimm-verify-action@v1

Travis CI

- wget -O swimm_cli https://releases.swimm.io/ci/latest/packed-swimm-linux-cli
- chmod +x ./swimm_cli
- ./swimm_cli verify

Circle CI

# Use the latest 2.1 version of CircleCI pipeline process engine. 
# See: https://circleci.com/docs/2.0/configuration-reference
version: 2.1
jobs:
swimm-verify:
docker:
- image: cimg/ubuntu:latest
steps:
- checkout
- run:
name: Run tests
command: |
git config --global user.name "Pretend User"
git config --global user.email "pretend@example.com"
wget -O swimm_cli https://releases.swimm.io/ci/latest/packed-swimm-linux-cli
chmod +x ./swimm_cli
./swimm_cli --version
./swimm_cli verify
workflows:
sample:
jobs:
- swimm-verify

Ordinarily, your workflows: section will already be defined, just put - swimm-verify under one of the defined jobs, where you want it to run.

Jenkins

The best way to run on Jenkins is through a "Freestyle Project", formerly known as a "Workflow". You can set up a project called "Swimm Verification" and point it at your repository, with whatever triggers or timing you'd like. There are only a few things that you have to watch out for:

  1. If you are using Jenkins' advanced clone configuration, make sure you disable the shallow pull option - Swimm is going to require that the entire history be present.

  2. You're going to need wget or curl installed, which you can do via apt-get install wget/apt-get install curl

Once you have that done, under Build, select "Execute Shell" and paste the following commands:

echo "Verifying documentation"
git config --global user.name "user.name"
git config --global user.email "youremail@domain.com"
wget -O swimm_cli https://releases.swimm.io/ci/latest/packed-swimm-linux-cl
chmod +x ./swimm_cli
./swimm_cli --version
./swimm_cli verify