Language Guide: Crystal
Tutorials & 2.0 Sample Apps > Language Guide: Crystal
This guide will help you get started with a minimal Crystal application on CircleCI.
Overview
If you’re in a rush, just copy the sample configuration below into a .circleci/config.yml
in your project’s root directory and start building.
You can view an example Crystal project at the following link:
In the project you will find a commented CircleCI configuration file .circleci/config.yml
.
The application uses Crystal 0.27 and Kemal 0.25. Both Crystal and Kemal are developing quickly. Altering the Docker image to the :latest
version may cause breaking changes.
Sample configuration
version: 2
jobs: # a collection of jobs
build:
working_directory: ~/demo_app
docker: # run build steps with docker
- image: crystallang/crystal:0.27.0 # primary docker container; all `steps` will run here.
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
steps: # a collection of executable steps
- checkout # checks out source code to working directory
- restore_cache: # Restore dependency cache
# Read about caching dependencies: https://circleci.com/docs/2.0/caching/
key: dependency-cache-{{ checksum "shard.lock" }}
- run:
name: Install dependencies.
command: shards install
- save_cache: # Step to save dependency cache
key: dependency-cache-{{ checksum "shard.lock" }}
paths:
- ./lib
- run:
name: test
command: crystal spec
# See https://circleci.com/docs/2.0/deployment-integrations/ for deploy examples
Config walkthrough
Every config.yml
starts with the version
key. This key is used to issue warnings about breaking changes.
version: 2
A run is comprised of one or more jobs. Because this run does not use workflows, it must have a build
job.
Use the working_directory
key to specify where a job’s steps
run. By default, the value of working_directory
is ~/project
, where project
is a literal string.
The steps of a job occur in a virtual environment called an executor. In this example, we use the official Crystal Docker image as our primary container. All commands for a job execute in this container.
jobs:
build:
working_directory: ~/demo_app
docker:
- image: crystallang/crystal:0.27.0
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
After choosing containers for a job, create steps
to run specific commands.
Use the checkout
step to check out source code. By default, source code is checked out to the path specified by working_directory
.
To save time between runs, consider caching dependencies or source code.
Use the save_cache
step to cache certain files or directories. In this example, the installed packages (“Shards”) are cached.
Use the restore_cache
step to restore cached files or directories. In this example, we use a checksum of the shard.lock
file to determine if the dependency cache has changed.
steps: #
- checkout
- restore_cache:
key: dependency-cache-{{ checksum "shard.lock" }}
- run:
name: Install dependencies.
command: shards install
- save_cache:
key: dependency-cache-{{ checksum "shard.lock" }}
paths:
- ./lib
Finally, we run crystal spec
to run the project’s test suite.
- run:
name: test
command: crystal spec
Great! You’ve set up CircleCI for a basic Crystal application.
Deploy
See the Deploy document for example deploy target configurations.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.