Skip to content

Commit 3336e00

Browse files
nateinactionnateinaction
committed
Add setup guide
1 parent ba3eb30 commit 3336e00

File tree

1 file changed

+139
-0
lines changed

1 file changed

+139
-0
lines changed

‎docs/additional-resources/self-hosted-runner-setup.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Setting up a self-hosted runner for Proves Core Reference builds
2+
3+
## Overview
4+
5+
### What is CI/CD?
6+
7+
**CI/CD** stands for **Continuous Integration** and **Continuous Deployment**. Think of it as an automated quality control system for software development:
8+
9+
- **Continuous Integration (CI)**: Automatically builds and tests code every time changes are made
10+
- **Continuous Deployment (CD)**: Automatically deploys tested code to production environments
11+
12+
### What is an automated build system?
13+
14+
An automated build system consists of machines that compile code, run tests, and sometimes deploy software. It automates the process of building software from source code, ensuring consistency and reliability in the build process.
15+
16+
**Here's what happens in our project when you make changes:**
17+
18+
1. **Code changes** are pushed to GitHub (via pull request or direct push)
19+
2. **Automated build** starts - compiles the firmware and F-Prime components
20+
3. **Tests run** - both unit tests and integration tests with real hardware
21+
4. **Results reported** - you see ✅ or ❌ status on our pull request
22+
5. **Build artifacts** are saved (like the `.uf2` firmware file)
23+
24+
This ensures that every change is automatically verified before it gets merged into the main codebase.
25+
26+
### GitHub Actions
27+
28+
GitHub Actions is a CI/CD platform that allows us to automate our software development workflows directly in our GitHub repository. It provides a way to define custom workflows using YAML files, which can include various actions such as building code, running tests, and deploying applications.
29+
30+
**Key concepts:**
31+
- **Workflow**: A automated process defined in a YAML file (like `.github/workflows/ci.yaml`)
32+
- **Job**: A set of steps that run on the same machine (like `build`, `lint`, `integration`)
33+
- **Step**: An individual task within a job (like "checkout code" or "run tests")
34+
- **Runner**: The machine that executes the workflow (GitHub-hosted or self-hosted)
35+
36+
**When workflows run:**
37+
- On every pull request (to test changes before merging)
38+
- When code is pushed to the main branch
39+
- On scheduled intervals (for nightly builds)
40+
- Manually triggered by developers
41+
42+
### Why We Need Self-Hosted Runners
43+
44+
Self-hosted runners are machines that you manage and maintain to run our GitHub Actions workflows. Unlike GitHub's hosted runners, which are provided and maintained by GitHub, self-hosted runners give you more control over the environment in which our workflows run.
45+
46+
We use self-hosted runners because they allow us to run tests on PROVES hardware that is connected to the runner machine. This is important because some tests require access to specific hardware components that are not available on GitHub's hosted runners.
47+
48+
### Understanding Pull Request Status Checks
49+
50+
When you create a pull request, you'll see status checks at the bottom that show the progress of our CI pipeline:
51+
52+
![Example of GitHub status checks](https://docs.github.com/assets/cb-17910/mw-1440/images/help/pull_requests/pr-checks-success.webp)
53+
54+
**Status meanings:**
55+
- **🟡 In Progress**: Tests are currently running
56+
- **✅ Passed**: All tests completed successfully
57+
- **❌ Failed**: One or more tests failed (click "Details" to see why)
58+
- **⏸️ Pending**: Waiting for previous jobs to complete
59+
60+
**Common failure scenarios:**
61+
For all failures, click "Details" next to the failed check to see logs and error messages. It's important to read these messages carefully to understand what went wrong.
62+
63+
- **Lint fails**: Code formatting and linting issues
64+
- Most likely running `make fmt` locally and committing the result will resolve
65+
- **Build fails**: Compilation errors
66+
- Run `make build` to troubleshoot
67+
- **Integration fails**: Hardware tests failed
68+
- Run `make test-integration` locally with the hardware connected to troubleshoot
69+
70+
### Development Workflow
71+
72+
Here's how CI/CD fits into a typical development process:
73+
74+
1. **Create a branch** from `main` for our feature
75+
2. **Make code changes** and commit them
76+
3. **Push to GitHub** - this triggers the build pipeline
77+
4. **Create a pull request** - this triggers the full CI pipeline
78+
5. **Wait for tests** - green checkmarks mean you're good to go
79+
6. **Address any failures** - fix issues and push new commits
80+
7. **Merge when green** - our code is automatically validated before merging
81+
82+
The CI system acts as a safety net, catching problems before they reach the main branch.
83+
84+
## Setting up a self-hosted runner
85+
86+
### Prerequisites
87+
88+
- A machine running a Linux distribution (Ubuntu is recommended)
89+
- A GitHub account with access to the repository where you want to set up the self-hosted runner
90+
- Basic knowledge of Linux command line and GitHub Actions
91+
- Sudo access on the machine
92+
93+
### Steps
94+
95+
1. **Install necessary software**: Ensure that the machine has required software installed.
96+
97+
```bash
98+
sudo apt update
99+
sudo apt install make cmake wget curl build-essential
100+
```
101+
102+
Install picotool (needed for flashing firmware to PROVES hardware):
103+
```bash
104+
curl https://github.com/raspberrypi/pico-sdk-tools/releases/download/v2.2.0-2/picotool-2.2.0-a4-x86_64-lin.tar.gz -o picotool-2.2.0-a4-x86_64-lin.tar.gz
105+
tar -xzf picotool-2.2.0-a4-x86_64-lin.tar.gz
106+
mv picotool-2.2.0-a4-x86_64-lin/picotool/* /usr/local/bin
107+
```
108+
109+
2. **Set permissions for USB access**: To allow the runner to access PROVES hardware connected via USB, we need to set appropriate permissions.
110+
111+
Add user to plugdev and dialout to give spacelab user usb perms
112+
```sh
113+
sudo usermod -a -G plugdev $USER
114+
sudo usermod -a -G dialout $USER
115+
```
116+
117+
Add udev rules to allow picotool to access USB without root
118+
```sh
119+
curl https://raw.githubusercontent.com/raspberrypi/picotool/refs/heads/master/udev/60-picotool.rules -o /etc/udev/rules.d/60-picotool.rules
120+
udevadm control --reload
121+
```
122+
123+
3. **Reboot the machine**: This ensures that all changes take effect, especially group membership changes.
124+
125+
```sh
126+
reboot
127+
```
128+
129+
4. **Download and configure the self-hosted runner**: Follow [GitHub's official documentation](https://github.com/organizations/Open-Source-Space-Foundation/settings/actions/runners/new?arch=x64&os=linux) to download and configure the self-hosted runner for our repository.
130+
131+
5. **Connect the PROVES hardware**: Ensure that the PROVES hardware is connected to the machine via USB.
132+
133+
6. **Run the self-hosted runner**: Start the runner using the provided script.
134+
135+
```sh
136+
./run.sh
137+
```
138+
139+
Ensure that you set our computer to not sleep or hibernate, as this will stop the runner. Also ensure that the runner is restarted if the machine reboots.

0 commit comments

Comments
 (0)