You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
HyperShift uses GitHub Actions for lightweight CI checks that run on every pull request. These workflows complement the heavier Prow-based e2e tests by providing fast feedback on code quality, formatting, and documentation.
4
4
5
-
## Reusable Workflow Architecture
5
+
## 🏗️ Reusable Workflow Architecture
6
6
7
7
All GHA workflows follow a **caller + reusable** pattern:
8
8
@@ -23,15 +23,15 @@ flowchart LR
23
23
24
24
This pattern provides:
25
25
26
-
-**Consistency** — all PR and push workflows share the same job definitions.
27
-
-**Maintainability** — job logic is defined once in the reusable workflow and updated in a single place.
28
-
-**Security** — callers pin reusable workflows to `@main`, reducing the risk of PRs altering reusable job logic. Caller workflows are protected by branch protection rules and CODEOWNERS.
26
+
-✅ **Consistency** — all PR and push workflows share the same job definitions.
27
+
-🔧 **Maintainability** — job logic is defined once in the reusable workflow and updated in a single place.
28
+
-🔒 **Security** — callers pin reusable workflows to `@main`, reducing the risk of PRs altering reusable job logic. Caller workflows are protected by branch protection rules and CODEOWNERS.
29
29
30
-
## Workflows
30
+
## 📋 Workflows
31
31
32
32
All workflows run on self-hosted ARC runners and target the `main` and `release-4.22` branches.
33
33
34
-
### Code Quality
34
+
### 🧹 Code Quality
35
35
36
36
| Caller | Reusable | Purpose |
37
37
|--------|----------|---------|
@@ -40,54 +40,116 @@ All workflows run on self-hosted ARC runners and target the `main` and `release-
40
40
|`lint.yaml`|`lint-reusable.yaml`| Go linting via `golangci-lint`|
41
41
|`verify.yaml`|`verify-reusable.yaml`| Full verification (`make verify`) |
42
42
43
-
### Testing
43
+
### 🧪 Testing
44
44
45
45
| Caller | Reusable | Purpose |
46
46
|--------|----------|---------|
47
47
|`test.yaml`|`test-reusable.yaml`| Unit tests with race detection and Codecov upload |
48
48
|`envtest-ocp.yaml`|`envtest-ocp-reusable.yaml`| CRD validation tests against OpenShift k8s versions |
49
49
|`envtest-kube.yaml`|`envtest-kube-reusable.yaml`| CRD validation tests against vanilla k8s versions |
50
50
51
-
### Documentation
51
+
### 📖 Documentation
52
52
53
53
| Caller | Reusable | Purpose |
54
54
|--------|----------|---------|
55
55
|`docs-build.yaml`|`docs-build-reusable.yaml`| Build MkDocs site in strict mode |
56
56
57
-
The `docs-deploy.yaml` workflow is not a reusable workflow pair — it triggers via `workflow_run` after the Docs Build completes to deploy the preview. See [Documentation Preview](docs-preview.md) for details.
57
+
!!! info
58
+
The `docs-deploy.yaml` workflow is not a reusable workflow pair — it triggers via `workflow_run` after the Docs Build completes to deploy the preview. See [Documentation Preview](docs-preview.md) for details.
58
59
59
-
### Other
60
+
### 🤖 PR Slash Commands
61
+
62
+
These workflows are triggered by posting a **slash command** as a comment on a pull request. They are powered by [Claude Code](https://docs.anthropic.com/en/docs/claude-code) via the shared `reusable-claude-on-pr.yaml` workflow, which handles checking out the PR branch, authenticating to GCP (for Vertex AI), and running Claude with the appropriate prompt.
63
+
64
+
!!! warning "Permissions"
65
+
Only organization **members**, **owners**, and **collaborators** can trigger these commands. Comments from external contributors are ignored.
66
+
67
+
| Command | Workflow | What it does |
68
+
|---------|----------|--------------|
69
+
|`/address-review-comments`|`address-review-comments.yaml`| Reads open review comments on the PR and pushes commits to address them |
70
+
|`/rebase`|`rebase.yaml`| Rebases the PR branch onto the latest `main` and force-pushes |
71
+
|`/restructure-commits`|`restructure-commits.yaml`| Reorganizes the PR's commits into logical units with conventional commit messages |
72
+
73
+
**How it works:**
74
+
75
+
1. Post the slash command (e.g., `/rebase`) as a comment on a PR.
76
+
2. The workflow posts a 🔗 reply comment linking to the Actions run so you can follow progress.
77
+
3. Claude checks out the PR branch, performs the requested operation, and pushes the result.
78
+
79
+
!!! tip
80
+
Each command uses concurrency groups scoped to the PR number — re-triggering a command automatically cancels the previous run for that PR.
81
+
82
+
### 🔧 Other
60
83
61
84
| Caller | Reusable | Purpose |
62
85
|--------|----------|---------|
63
86
|`cpo-container-sync.yaml`|`cpo-container-sync-reusable.yaml`| Validate CPO container image references are in sync |
64
87
|`dependabot-commit-fix.yaml`|`dependabot-commit-fix-reusable.yaml`| Rewrite dependabot commit messages to pass gitlint |
88
+
|`gocacheprog-test.yaml`|`gocacheprog-test-reusable.yaml`| Tests for the `contrib/ci/gocacheprog` build cache tool (path-filtered) |
89
+
|`validate-cpo-overrides.yaml`| — | Validate CPO override images exist and are pullable |
65
90
66
-
The `sync-community-fork.yaml` workflow runs on push to `main` only (not on PRs) and does not use the reusable pattern. See [Sync Community Fork](sync-community-fork.md) for details.
91
+
!!! note
92
+
The `sync-community-fork.yaml` workflow runs on push to `main` only (not on PRs) and does not use the reusable pattern. See [Sync Community Fork](sync-community-fork.md) for details.
67
93
68
-
## Adding a New Workflow
94
+
## ➕ Adding a New Workflow
69
95
70
96
To add a new GHA workflow:
71
97
72
-
1. Create the reusable workflow (e.g., `my-check-reusable.yaml`) with `on: workflow_call`.
73
-
2. Create the caller workflow (e.g., `my-check.yaml`) that uses the reusable workflow pinned at `@main`.
74
-
3. Add branch filters for `main` and any active release branches.
98
+
1.**Create the reusable workflow** (e.g., `my-check-reusable.yaml`) with `on: workflow_call`. This is where all the job logic lives.
99
+
2.**Create the caller workflow** (e.g., `my-check.yaml`) that uses the reusable workflow pinned at `@main`.
100
+
3. Add **branch filters** for `main` and any active release branches (e.g., `release-4.22`).
75
101
4. Use `arc-runner-set` as the runner.
76
102
77
-
Example caller:
103
+
### Post-merge runs
104
+
105
+
If your workflow should also run after PRs merge to `main` (e.g., for Codecov baseline uploads or post-merge validation), add `on: push` triggers **to the reusable workflow**, not the caller. This lets the reusable workflow run directly on push events without needing a separate caller.
78
106
79
-
```yaml
80
-
name: My Check
107
+
### Why callers pin to `@main`
81
108
82
-
on:
83
-
pull_request:
84
-
branches:
85
-
- main
86
-
- release-4.22
109
+
Callers reference the reusable workflow at `@main` (e.g., `uses: openshift/hypershift/.github/workflows/my-check-reusable.yaml@main`). This means a PR **cannot modify the reusable workflow logic that runs against itself** — it always executes the version from `main`. This is a deliberate security measure: it prevents a PR from weakening checks to make itself pass.
110
+
111
+
!!! warning "Implication for new workflows"
112
+
When you add a new reusable workflow, the caller in the same PR will **not** be able to reference it until it lands on `main`. You'll need to merge the reusable workflow first (or together with the caller, accepting that the first PR run will use a stale/missing reference).
![openshift-merge-bot[bot]](https://avatars.githubusercontent.com/in/412865?v=4&size=40){kind=avatar}
0 commit comments