Build open source projects
This document provides tips and best practices for building your open source project on CircleCI.
Credits for open source projects
See the Using Credits page for up-to-date information on free credits available for open source projects.
Security
While open source can be a liberating practice, take care not to liberate sensitive information.
-
If your repository is public, your CircleCI project and its build logs are also public. Pay attention to the information you choose to print.
-
Environment variables set in the CircleCI application are hidden from the public. These variables will not be shared in forked PRs unless explicitly enabled.
Features and settings for open source projects
The following features and settings can be useful for open source projects.
Private environment variables
Many projects require API tokens, SSH keys, or passwords. Private environment variables allow you to safely store secrets, even if your project is public.
For more information, see the Set an Environment Variable document.
Only build pull requests
Open source projects have significantly more commits than private projects, so building every commit from every branch might be excessive and costly (both in terms of time and credits usage).
You can modify this behaviour by restricting builds to branches that have pull requests. For steps, see the Pull Request Build Settings page.
Build pull requests from forked repositories
Many open source projects accept PRs from forked repositories. Building these PRs is an effective way to catch bugs before manually reviewing changes. For steps, see Build Pull Requests From Forked Repositories.
Pass secrets to builds from forked pull requests
Running an unrestricted build in a parent repository can be dangerous. Projects often contain sensitive information, and this information is freely available to anyone who can push code that triggers a build. For what CircleCI hides by default and how to turn this setting on, see Pass Secrets to Builds From Forked Pull Requests.
Caching
For how caches work in builds from forked pull requests, see Caching in Forked Pull Request Builds.
Example open source projects
Following are a few examples of projects (big and small) that build on CircleCI:
See also
Refer to the Examples document for more public and open source project configuration links organized by CircleCI features and by programming language.
