Continuous integration / continuous development (CI/CD) is a workflow that catches bugs during development at the earliest possible opportunity. It works by running tests on the source code that is committed to the GitLab repository. If a one of the tasks fails on a commit you made, then a bug may have been introduced into the source code and needs to be corrected.
## Why did my commit fail CI?
On every commit, a script runs that performs a number of things, including
compiling code and running unit and functional tests. Whatever you did
apparently broke one of these things.
## Why should I care about the CI results?
CI _immensely_ streamlines the development cycle by helping us catch bugs
immediately, allowing us to fix them early before they plague us (or future
users of the code base). It's a common industry practice. If you break the CI
pipeline, don't ignore it! Try your best to get the branch back in working
condition.
## Okay, so my commit failed CI, and I guess I care. What should I do?
1. Re-run the build.
- Sometimes something weird happens, so it's good to check this.
2. Figure out what you did wrong and fix it.
- If you click on the build, you should be able to see the exact logs of the
build process. Debug the error to figure out what went wrong. Maybe you
failed a test. You may need to open the source code for the test to see
where you failed, which is very insightful into figuring out what went
wrong.
3. Figure out what CI is doing wrong.
- Sometimes a test might be poorly designed. At this point, it can be really
tempting to just ignore the build failure altogether (don't do that!), or
just remove the broken test (not as bad, but still don't do that). The best
thing is to fix the test so that we continue to have good regression
test coverage over our code.
## My build failed due to unavailable software. How do I install things on CI?
Each build is run within a docker image. Add whatever software you need on the
`sudo apt install ...` line inside of the `.gitlab-ci.yml` file in the root
directory.
## How does CI work?
When a commit is added to a branch in our repository, a notification is sent out
to our gitlab-ci-runner, which instructs it to checkout the updated branch and
run the directive in [`.gitlab-ci.yml`](/../blob/master/%2Egitlab-ci%2Eyml). It then runs each directive. This script file is broken into two major stages, `build` and `unit-tests`. The stages are ran sequentially, the `build` stage simply compiles the Crazyflie firmware and ensures it builds without error. The `unit-tests` stage builds and runs unit tests on the Crazyflie firmware to ensure no errors. The unit tests are written with in the firmware. If some error occurs during execution (perhaps a forced error generated by a failed test), then the runner sends a message back to Gitlab indicating that the CI failed. Otherwise, it succeeds.
## CI Server Setup
All CI jobs are run by the `gitlab runner` which is installed on ISU server `microcart.ece.iastate.edu`. The current version of the gitlab runner installed is 14.5.0 from 2021. The server can be connected to through the SSH username and password stored in the hidden CI/CD variables (These are only visible to administrators of the GitLab project). The SSH credentials can be found under settings > CI/CD > Variables > Reveal values.
More details on the server setup can be found under [System Details](System-Details.md).
