How to contribute to the Cozy Stack?

Thank you for your interest in contributing to Cozy! There are many ways to contribute, and we appreciate all of them.

Security Issues

If you discover a security issue, please bring it to their attention right away! Please DO NOT file a public issue, instead send your report privately to security AT cozycloud DOT cc.

Security reports are greatly appreciated and we will publicly thank you for it. We currently do not offer a paid security bounty program, but are not ruling it out in the future.

Bug Reports

While bugs are unfortunate, they’re a reality in software. We can’t fix what we don’t know about, so please report liberally. If you’re not sure if something is a bug or not, feel free to file a bug anyway.

Opening an issue is as easy as following this link and filling out the fields. Here are some things you can write about your bug:

You can also use the cozy-stack bug command to open the form to report issue prefilled with some useful system informations.

Pull Requests


Pull requests are the primary mechanism we use to change Cozy. GitHub itself has some great documentation on using the Pull Request feature. We use the ‘fork and pull’ model described there.

Step 1: Fork

Fork the project on GitHub and check out your copy locally.

$ go get -u
$ cd $(go env GOPATH)/src/
$ git remote add fork git://

Step 2: Branch

Create a branch and start hacking:

$ git checkout -b my-branch -t origin/master

Step 3: Code

Well, I think you know how to do that. Just be sure to follow the coding guidelines from the Go community (gofmt, Effective Go, comment the code, etc.).

We are using goimports to format code, and golangci-lint to detect code smells.

Step 4: Test

Don’t forget to add tests and be sure they are green:

$ go test -v ./...

If you want to play with the modified cozy-stack (for example, testing it with a webapp), you can build it locally and start it with this command:

$ go build && ./cozy-stack serve

Step 5: Commit

Writing good commit messages is important. A commit message should describe what changed and why.

Step 6: Rebase

Use git rebase (not git merge) to sync your work from time to time.

$ git fetch origin
$ git rebase origin/master

Step 7: Push

$ git push fork my-branch

Go to and select your branch. Click the ‘Pull Request’ button and fill out the form.

Pull requests are usually reviewed within a few days. If there are comments to address, apply your changes in a separate commit and push that to your branch. Post a comment in the pull request afterwards; GitHub does not send out notifications when you add commits.

Code organization

The codebase of cozy-stack contains several packages, and it is quite easy to have circular import issues in go. To limit the risk, we have split the packages in several directories with some rules for the imports. In short, a package in this list should import other packages that are on the same line or below:

Note that tests/testutils can be used safely in web and worker packages. In model, it can be used but it is recommended to use a fake package for the tests if it is the case. For example, model/oauth/client_test.go is declared as package oauth_test.

External assets

The cozy-stack serve some assets for the client application. In particular, cozy-client-js and cozy-bar assets are listed in assets/external. To update them, you can open a pull request for this file. When a maintainer will accept this pull request, he will also run scripts/ assets to transform them in go code (to make the repository go gettable).

Useful commands

There are some useful commands to know in order to develop with the go code of cozy-stack:

go get -u
cd $(go env GOPATH)/src/

go get -t -u ./...      # To install or update the go dependencies
go test -v ./...        # To launch the tests
go run main.go serve    # To start the API server
godoc -http=:6060       # To start the documentation server
                        # Open

Writing documentation

Documentation improvements are very welcome. We try to keep a good documentation in the docs/ folder. But, you know, we are developers, we can forget to document important stuff that look obvious to us. And documentation can always be improved.


The Cozy Stack is translated on a platform called Transifex. This tutorial can help you to learn how to make your first steps here. If you have any question, don’t hesitate to ask us!

The translations are imported from transifex with tx pull -a in the assets/locales directory, and packed in the go code with scripts/ assets.


You can help us by making our community even more vibrant. For example, you can write a blog post, take some videos, answer the questions on the forum, organize new meetups, and speak about what you like in Cozy!