Continuous Integration with CircleCI
Here is a tutorial on how to integrate your repository onto Circleci.
Log in to CircleCI with your github account. You should be able to switch to the PurdueCAM2Project account (as shown on the top left corner of the picture). Go to add project on the left side bar. We run our containers under Linux. Projects that you can follow/unfollow are already integrated with CircleCI; projects that has a lock asking you to "contact admin" means that your Github account does not have the admin right for configuring CircleCI here. You can click and setup CircleCI for repository that has a blue "Set Up Project" button. Click on the button of the repository you would like to integrate with CircleCI.
You will jump to the setup page. The default system is Linux and programing language of the repository is detected. You should not need to change anything in this step, unless the repository used a very heterogenous composition of languages.
Follow the setup steps. A basic config.yml file according to the selected system and programming language is generated for you. Please refer the the documentation link on the page for more detailed CircleCI configuration. You could also refer to the CicleCI configuration files in .circleci/config.yml files in CameraDatabaseClient and CameraDatabaseAPI repository.
When you have successfully setup the project in CircleCI, go to the project repository in Github. Under Settings->Deploy keys, you will see a new deploy key (public) added automatically by Circleci. The same key (private) is added to CircleCI under project setting dashboard PERMISSIONS->Checkout SSH Keys. The key has read-only permission on the repository, allowing CircleCI to pull code from project githhub repository and run tests in the container.
Writing to the project repository (i.e. Automatically generate documentation and push to gh-pages branch) requires CircleCI to have write permission on the repository. If you do not plan to let CircleCI write to your repository, you can stop here and you have finished integrating your project repository to Circleci! 🤓
(for script generating documentation automatically when there is change in master branch, refer to the config.yml and generate-docs.sh in CameraDatabaseAPI and CameraDatabaseClient repositories.
If you are integrating CircleCI for your personal project, you could click on the Authorize with GitHub to add a user key to CircleCI, and CircleCI will write to the repository on your GitHub account's behalf.
Integrating CircleCI with a CAM2 project, it will be optimal if you generate an key with write access to CircleCI itself, so that other members can still configure the project after you leave the team. There are 2 options:
(a). Log in CircleCI with our cam2circleci GitHub account, and add user key with this account, which is dedicated only for CAM2 CircleCI integration.
(b).
-
Generate an SSH key pair on your local machine (you can refer to the tutorial here)
Paste the generated public key to GitHub repository, and be sure to check the box beneath to give it write access.
Paste the private key to CircleCI in PERMISSION->SSH Permissions. For host name, enter "gitHub.com".
Add the SSH key fingerprint to .circleci/config.yml in your project repository, so that circleci knows it should use this key.
In the documentation generation script (.circleci/generation-docs.sh file), we specify that the circleci GitHub account pushed the changed documentation. Please refer to .circleci/generation-docs.sh in CameraDatabaseAPI and CameraDatabaseClient for configuring account username and email.
Add these environment variables in CircleCI Build Settings->Environment Variables.
Now we have finished CircleCI integration with auto documentation generation!