I am not a developer, but I work with developer tools all day. This can be frustrating, because a lot of tools made for developers assuming knowledge that I’m lacking.
Of course, if that wasn’t the case there would be less need for technical writers and my work would be harder to come by!
In any case, After spending the last few days migrating my job’s documentation to use the CircleCI 2.0 configuration, here are some tips I picked up:
This can be tricky if you don’t keep it in mind. Because CircleCI tests are run in a non-interactive environment, your output can get …funky. For example, here’s the output of
sculpin generate, which we use to turn our markdown files into html, running locally through CircleCI CLI:
Here’s the output from the build on CircleCI’s platform:
Sculpin assumes an interactive shell in which it can rewrite its output as it goes. CircleCI’s environment is set for better logging, not better human readbility (as it should be).
This is of course a trivial example, as I could add
--quiet to my generate command to make my CI output nicer. But that’s not always the case…
Rsync output on CircleCI
Part of my build process involves copying my compiled docs to a staging environment. Our scripts use
rsync, the most common choice for transferring files from A to B.
No matter what permutation of logging flags I gave rsync, the only output I could get from my CI builds was empty, or a list of every single file it was checking for changes:
Not a critical problem, but it certainly reduces the usefulness of the output.
While I could pipe the rsync command directly through
grep, that would interfere with the
while loop I put rsync in, which checks for exit codes to determine success. Instead, I constructed my rsync command as follows:
rsync --checksum --delete-after -rtlzq --ipv4 --info=BACKUP,DEL --log-file=multidev-log.txt -e 'ssh -p 2222 -oStrictHostKeyChecking=no' output_prod/docs/ --temp-dir=../../tmp/ $normalize_branch.$STATIC_DOCS_UUID@appserver.$normalize_branch.$STATIC_DOCS_UUID.drush.in:files/docs/
That’s a lot to unpack, I know. The key flags are
-q, which keeps the output quiet, and
--log-file=./multidev-log.txt, to redirect output into a log file. Then, once my loop has exited, I can run:
cat ./multidev-log.txt | egrep '<|>|deleting' || true
My pipe to
egrep searches for the characters
>, or the word
deleting. Using the OR operator
|| true means that even if the grep returns no results the line will still exit with code
0, keeping my script from failing.
Now my output is concise and useful!
(By the way, I learned a lot of useful information about rsync output from this blog post, run through Google Translate.)
Dockerize for background processes
IMHO, this tool is poorly named. While it’s purpose was originally for CI builds involving multiple docker containers (I assume), it’s helpful even in a single container environment.
I was seeing intermittent build failures coming from my Behat tests:
Behat is configured to look at port
8000 for my Sculpin server to serve the files it tests. The Sculpin step wasn’t failing, but rather it wasn’t starting up fast enough.
My initial response to this problem was to add
sleep 5 to my Behat step, giving Sculpin more time to initialize. But then my friend Ricardo told me about Dockerize. Because my Docker image is built from a CircleCI image, it was already installed. So I added a new step in
name: Start Sculpin
command: /documentation/bin/sculpin server
name: Wait for Sculpin
command: dockerize -wait tcp://localhost:8000 -timeout 1m
Dockerize checks for a service listening on the port, and retries if one isn’t found:
Now I have one less reason for my builds to fail…
Do you have any tips, tricks, or answers to common “Gotchas” for continuous integration testing? If so, please share them!