Skip to content

Commit bdd7987

Browse files
ashraffoudaashraffouda
committed
docs for workflows
Signed-off-by: Ashraf Fouda <ashraf.m.fouda@gmail.com>
1 parent ea6dd89 commit bdd7987

12 files changed

Lines changed: 305 additions & 0 deletions

‎docs/workflows/bin-package-18.04.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# bin-package-18.04
2+
3+
**File:** `.github/workflows/bin-package-18.04.yaml`
4+
**Trigger:** Called by other workflows (`workflow_call`)
5+
6+
## Purpose
7+
8+
Builds a single runtime package using an **Ubuntu 18.04** container. This is identical to `bin-package` but forces the older Ubuntu version for packages that require it (e.g. `mdadm`).
9+
10+
## Inputs
11+
12+
| Input | Required | Description |
13+
|-------|----------|-------------|
14+
| `package` | Yes | Name of the package to build |
15+
16+
## Secrets
17+
18+
| Secret | Description |
19+
|--------|-------------|
20+
| `token` | Hub JWT token for publishing flists |
21+
22+
## Steps
23+
24+
1. **Checkout** the repository
25+
2. **Set tag**: Determines the version reference — uses git tag name for tag pushes, or short SHA for branch pushes
26+
3. **Setup basesystem**: Runs `bins/bins-extra.sh --package basesystem` to install build prerequisites
27+
4. **Build package**: Runs `bins/bins-extra.sh --package <package>` to compile the binary
28+
5. **Publish flist**: Uploads the built binary as an flist to `tf-autobuilder/<package-name>.flist` on the hub
29+
6. **Tagging**: On `main`, `testdeploy`, or version tags (`v*`), creates a tag link `<reference>/<package>.flist` pointing to the published flist

‎docs/workflows/bin-package-no-tag.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# bin-package-no-tag
2+
3+
**File:** `.github/workflows/bin-package-no-tag.yaml`
4+
**Trigger:** Called by other workflows (`workflow_call`)
5+
6+
## Purpose
7+
8+
Builds a single runtime package using Ubuntu 20.04 but **never tags** the built binary. This means any package built with this workflow never becomes part of a ZOS installation release. Used for packages like `qsfs` and `traefik` that are published independently.
9+
10+
## Inputs
11+
12+
| Input | Required | Description |
13+
|-------|----------|-------------|
14+
| `package` | Yes | Name of the package to build |
15+
16+
## Secrets
17+
18+
| Secret | Description |
19+
|--------|-------------|
20+
| `token` | Hub JWT token for publishing flists |
21+
22+
## Steps
23+
24+
1. **Checkout** the repository
25+
2. **Setup basesystem**: Installs build prerequisites via `bins/bins-extra.sh --package basesystem`
26+
3. **Build package**: Compiles the binary via `bins/bins-extra.sh --package <package>`
27+
4. **Publish flist**: Uploads the built binary as an flist to `tf-autobuilder/<package-name>.flist` on the hub
28+
29+
No tagging step is performed — the flist is published but not linked to any release version.

‎docs/workflows/bin-package.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# bin-package
2+
3+
**File:** `.github/workflows/bin-package.yaml`
4+
**Trigger:** Called by other workflows (`workflow_call`)
5+
6+
## Purpose
7+
8+
Builds a single runtime package using Ubuntu 20.04. The built binary is always published to `tf-autobuilder` and then tagged with the release version or the short SHA of the commit head (on main branch). This is the standard build workflow invoked by `bins.yaml` for most packages.
9+
10+
## Inputs
11+
12+
| Input | Required | Description |
13+
|-------|----------|-------------|
14+
| `package` | Yes | Name of the package to build |
15+
16+
## Secrets
17+
18+
| Secret | Description |
19+
|--------|-------------|
20+
| `token` | Hub JWT token for publishing flists |
21+
22+
## Steps
23+
24+
1. **Checkout** the repository
25+
2. **Set tag**: Determines the version reference — uses git tag name for tag pushes (e.g. `v1.2.3`), or short SHA for branch pushes
26+
3. **Setup basesystem**: Runs `apt update` then `bins/bins-extra.sh --package basesystem`
27+
4. **Build package**: Compiles the binary via `bins/bins-extra.sh --package <package>`
28+
5. **Publish flist**: On `main`, `testdeploy`, or version tags, uploads to `tf-autobuilder/<package-name>.flist`
29+
6. **Tagging**: On `main`, `testdeploy`, or version tags, creates a tag link `<reference>/<package>.flist` pointing to the published flist

‎docs/workflows/bins.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# bins (Runtime Packages)
2+
3+
**File:** `.github/workflows/bins.yaml`
4+
**Trigger:** Push to any branch, or version tags (`v*`)
5+
6+
## Purpose
7+
8+
Orchestrates the build of **all runtime packages** that ZOS depends on. Each package is built in parallel by calling one of the reusable workflows:
9+
10+
- `bin-package.yaml` — standard build + tag (most packages)
11+
- `bin-package-18.04.yaml` — build on Ubuntu 18.04 (for packages requiring older glibc)
12+
- `bin-package-no-tag.yaml` — build without tagging (packages managed independently)
13+
14+
## Packages
15+
16+
### Standard packages (bin-package)
17+
18+
| Package | Description |
19+
|---------|-------------|
20+
| `containerd` | Container runtime |
21+
| `runc` | OCI runtime |
22+
| `virtwhat` | Hypervisor detection |
23+
| `yggdrasil` | Overlay network daemon |
24+
| `rfs` | Remote filesystem |
25+
| `hdparm` | Disk parameters tool |
26+
| `corex` | Container interactive shell |
27+
| `shimlogs` | Container log shim |
28+
| `cloudhypervisor` | VM hypervisor |
29+
| `tailstream` | Log tail streaming |
30+
| `virtiofsd` | Virtio filesystem daemon |
31+
| `vector` | Log/metrics collection |
32+
| `nnc` | Network connectivity checker |
33+
| `lshw` | Hardware lister |
34+
| `cloudconsole` | Cloud console |
35+
| `misc` | Miscellaneous tools |
36+
| `iperf` | Network performance |
37+
| `cpubench` | CPU benchmarking |
38+
| `mycelium` | Mycelium network daemon |
39+
40+
### Ubuntu 18.04 packages (bin-package-18.04)
41+
42+
| Package | Description |
43+
|---------|-------------|
44+
| `mdadm` | RAID management |
45+
46+
### No-tag packages (bin-package-no-tag)
47+
48+
| Package | Description |
49+
|---------|-------------|
50+
| `qsfs` | Quantum Safe File System |
51+
| `traefik` | Reverse proxy |

‎docs/workflows/codeql-analysis.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# CodeQL Analysis
2+
3+
**File:** `.github/workflows/codeql-analysis.yml`
4+
**Trigger:**
5+
- Push to `main`
6+
- Pull requests targeting `main`
7+
- Scheduled: every Wednesday at 11:00 UTC
8+
9+
## Purpose
10+
11+
Runs GitHub's CodeQL static analysis tool on the Go codebase to find security vulnerabilities and code quality issues.
12+
13+
## Steps
14+
15+
1. **Checkout** the repository (with depth 2 for PR head detection)
16+
2. **Initialize CodeQL** for Go language scanning
17+
3. **Autobuild** — CodeQL automatically detects and builds the Go project
18+
4. **Perform analysis** — runs the CodeQL queries and reports findings

‎docs/workflows/grid-deploy.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Grid Deploy
2+
3+
**File:** `.github/workflows/grid-deploy.yaml`
4+
**Trigger:** Manual dispatch (`workflow_dispatch`)
5+
6+
## Purpose
7+
8+
Deploys a specific ZOS version to a target grid environment (qa, testing, or production) by creating a cross-link on the hub. This effectively makes the specified version the "latest" for that grid.
9+
10+
## Inputs
11+
12+
| Input | Required | Default | Description |
13+
|-------|----------|---------|-------------|
14+
| `grid` | Yes | `qa` | Target grid environment (`qa`, `testing`, or `production`) |
15+
| `version` | Yes | — | Version string to deploy (e.g. the flist version tag) |
16+
17+
## Steps
18+
19+
1. **Symlink flist**: Creates a cross-link so that `tf-zos/zos:<grid>-3:latest.flist` points to `tf-autobuilder/zos:<version>.flist`
20+
21+
This is the mechanism used to promote a tested build to a specific grid environment.

‎docs/workflows/publish-bootstrap.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Publish Bootstrap
2+
3+
**File:** `.github/workflows/publish-bootstrap.yaml`
4+
**Trigger:** Push to files in `bootstrap/bootstrap/**` or changes to the workflow file itself
5+
6+
## Purpose
7+
8+
Builds and publishes the ZOS bootstrap binary. The bootstrap is a Rust binary compiled with musl for static linking, which is responsible for downloading and starting all ZOS services on node boot.
9+
10+
## Steps
11+
12+
1. **Checkout** the repository
13+
2. **Prepare musl**: Installs `musl` and `musl-tools` for static compilation
14+
3. **Setup Rust toolchain**: Configures stable Rust with `x86_64-unknown-linux-musl` target
15+
4. **Build bootstrap**: Runs `make release` in `bootstrap/bootstrap/`
16+
5. **Collect files**: Copies the built binary to `archive/sbin/bootstrap`
17+
6. **Set name**: Generates a versioned name like `bootstrap-v<YYMMDD.HHMMSS.0>-dev.flist`
18+
7. **Publish flist**: Uploads to `tf-autobuilder/<name>.flist`
19+
8. **Symlink (development)**: Always creates symlink `bootstrap:development.flist` pointing to the new build
20+
9. **Symlink (release)**: On `main` branch only, also creates symlink `bootstrap:latest.flist`

‎docs/workflows/publish.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Publish (Release)
2+
3+
**File:** `.github/workflows/publish.yaml`
4+
**Trigger:** Push to any branch, or version tags (`v*`)
5+
6+
## Purpose
7+
8+
Builds all ZOS Go binaries (the core daemons) and publishes them as a single flist. This is the main release workflow for ZOS itself (as opposed to `bins.yaml` which handles runtime dependencies).
9+
10+
## Steps
11+
12+
1. **Set up Go 1.23**
13+
2. **Checkout** the repository
14+
3. **Build binaries**: Runs `make` in the `cmds/` directory to compile all ZOS daemons
15+
4. **Set tag**: Determines version reference — tag name for releases, short SHA for branches
16+
5. **Set version**: Generates a timestamped version like `v<YYMMDD.HHMMSS.0>`
17+
6. **Collect files**: Runs `scripts/collect.sh` to gather all binaries and zinit configs into an archive
18+
7. **Publish flist**: Uploads `zos:<version>.flist` to `tf-autobuilder`
19+
8. **Tagging**: On `main`, `testdeploy`, or version tags, creates a tag link `<reference>/zos.flist`
20+
9. **Cross tagging (development)**: On `main` or `testdeploy`, cross-tags the build to `tf-zos/development`, making it the latest development release
21+
22+
## Release Flow
23+
24+
```
25+
Push to main
26+
→ Build all daemons
27+
→ Publish as zos:<version>.flist
28+
→ Tag as <short-sha>/zos.flist
29+
→ Cross-tag to tf-zos/development (devnet)
30+
31+
Push tag v*
32+
→ Build all daemons
33+
→ Publish as zos:<version>.flist
34+
→ Tag as <tag>/zos.flist
35+
36+
Manual grid-deploy workflow
37+
→ Links tf-zos/zos:<grid>-3:latest.flist → tf-autobuilder/zos:<version>.flist
38+
```

‎docs/workflows/test-bootstrap.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Bootstrap Tests
2+
3+
**File:** `.github/workflows/test-bootstrap.yaml`
4+
**Trigger:** Push to files in `bootstrap/bootstrap/**` or changes to the workflow file itself
5+
6+
## Purpose
7+
8+
Runs tests for the ZOS bootstrap binary (Rust) and verifies it compiles successfully.
9+
10+
## Steps
11+
12+
1. **Checkout** the repository
13+
2. **Prepare musl**: Installs `musl` and `musl-tools`
14+
3. **Setup Rust toolchain**: Configures stable Rust with `x86_64-unknown-linux-musl` target
15+
4. **Test**: Runs `make test` in `bootstrap/bootstrap/`
16+
5. **Build**: Runs `make release` to verify the release build compiles

‎docs/workflows/test.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Tests and Coverage
2+
3+
**File:** `.github/workflows/test.yaml`
4+
**Trigger:** Push to any branch
5+
6+
## Purpose
7+
8+
Runs tests and verifies the ZOS Go codebase compiles. Currently the test steps are commented out — only a build verification is performed.
9+
10+
## Steps
11+
12+
1. **Set up Go 1.23**
13+
2. **Prepare dependencies**: Installs `libjansson-dev` and `libhiredis-dev`
14+
3. **Checkout** the repository
15+
4. **Build binaries**: Runs `make` in `cmds/` to verify compilation
16+
17+
## Note
18+
19+
The actual test execution (`make testrace`) and dependency fetching (`make getdeps`) steps are currently commented out in the workflow.

0 commit comments

Comments
 (0)