Skip to content

Quick Start

At the moment Cirrus CI only supports repositories hosted on GitHub. This guide will walk you through the installation process. If you are interested in a support for other code hosting platforms please fill up this form to help us prioritize the support and notify you once the support is available.

Start by configuring the Cirrus CI application from GitHub Marketplace.

Choose a plan for your personal account or for an organization you have admin writes for.

GitHub Apps can be installed on all repositories or on repository-by-repository basis for granular access control. For example, Cirrus CI can be installed only on public repositories and will only have access to these public repositories. In contrast, classic OAuth Apps don't have such restrictions.

Change Repository Access

You can always revisit Cirrus CI's repository access settings on your installation page.

Post Installation

Once Cirrus CI is installed for a particular repository, you must add either .cirrus.yml configuration or .cirrus.star script to the root of the repository. The .cirrus.yml defines tasks that will be executed for every build for the repository.

For a Node.js project, your .cirrus.yml could look like:

container:
  image: node:latest

check_task:
  node_modules_cache:
    folder: node_modules
    fingerprint_script: cat yarn.lock
    populate_script: yarn install
  test_script: yarn test

arm_container:
  image: node:latest

check_task:
  node_modules_cache:
    folder: node_modules
    fingerprint_script: cat yarn.lock
    populate_script: yarn install
  test_script: yarn test

That's all! After pushing a .cirrus.yml a build with all the tasks defined in the .cirrus.yml file will be created.

Note: Please check the full guide on configuring Cirrus Tasks and/or check a list of available examples.

Zero-config Docker Builds

If your repository happened to have a Dockerfile in the root, Cirrus CI will attempt to build it even without a corresponding .cirrus.yml configuration file.

You will see all your Cirrus CI builds on cirrus-ci.com once signed in.

GitHub status checks for each task will appear on GitHub as well.

Newly created PRs will also get Cirrus CI's status checks.

Examples

Don't forget to check examples page for ready-to-copy examples of some .cirrus.yml configuration files for different languages and build systems.

Life of a build

Please check a high level overview of what's happening under the hood when a changed is pushed and this guide to learn more about how to write tasks.

Authorization on Cirrus CI Web App

All builds created by your account can be viewed on Cirrus CI Web App after signing in with your GitHub Account:

After clicking on Sign In you'll be redirected to GitHub in order to authorize access:

Note about Act on your behalf

Cirrus CI only asks for several kinds of permissions that you can see on your installation page. These permissions are read-only except for write access to checks and commit statuses in order for Cirrus CI to be able to report task statuses via checks or commit statuses.

There is a long thread disscussing this weird "Act on your behalf" wording here on GitHub's own commuity forum.

Enabling New Repositories after Installation

If you choose initially to allow Cirrus CI to access all of your repositories, all you need to do is push a .cirrus.yml to start building your repository on Cirrus CI.

If you only allowed Cirrus CI to access certain repositories, then add your new repository to the list of repositories Cirrus CI has access to via this page, then push a .cirrus.yml to start building on Cirrus CI.

Permission Model for GitHub Repositories

When a user triggers a build on Cirrus CI by either pushing a change to a repository, creating a PR or a release, Cirrus CI will associate a corresponding user's permissions with the build and tasks within that build. Those permissions are exposed to tasks with CIRRUS_USER_PERMISSIONS environment variable and are mapped to GitHub's collaborator permissions. of the user for the given repository. Only tasks with write and admin permissions will be get decrypted values of the encrypted variables.

When working with Cirrus GraphQL API either directly or indirectly through Cirrus CI Web UI, permissions play a key role. Not only one need read permission to view a certain build and tasks of a private repository, but in order to perform any GraphQL mutation one will need at least write permission with a few exceptions:

  • admin permission is required for deleting a repository via RepositoryDeleteMutation.
  • admin permission is required for creating API access tokens via GenerateNewOwnerAccessTokenMutation and GenerateNewScopedAccessTokenMutation.

Note that for public repositories none collaborator permission is mapped to read in order to give public view access to anyone.