Skip to content

Commit f2c7b2e

Browse files
Copilotalexlovelltroy
Copilot
and
alexlovelltroy
committed
Add comprehensive documentation for reusing the central GitHub Actions workflow
Co-authored-by: alexlovelltroy <845272+alexlovelltroy@users.noreply.github.com>
1 parent 1965bc6 commit f2c7b2e

File tree

3 files changed

+345
-1
lines changed

3 files changed

+345
-1
lines changed

‎README.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ The **OpenCHAMI cloud-init service** retrieves detailed inventory information fr
2424
- [Cluster Defaults and Instance Overrides](#cluster-defaults-and-instance-overrides)
2525
- [Set Cluster Defaults](#set-cluster-defaults)
2626
- [Override Instance Data](#override-instance-data)
27-
6. [More Reading](#more-reading)
27+
6. [CI/CD and Workflow Reuse](#cicd-and-workflow-reuse)
28+
7. [More Reading](#more-reading)
2829

2930
---
3031

@@ -78,6 +79,54 @@ export BUILD_USER=$(whoami)
7879
7980
---
8081

82+
## CI/CD and Workflow Reuse
83+
84+
This project uses a centralized, reusable GitHub Actions workflow for building and releasing Go applications. The workflow is defined in the [OpenCHAMI/github-actions](https://github.com/OpenCHAMI/github-actions) repository and can be used by other projects.
85+
86+
### Using This Workflow in Your Project
87+
88+
You can reuse the same release workflow in your own Go projects. The workflow provides:
89+
- Multi-architecture builds (amd64, arm64)
90+
- Container image creation and publishing
91+
- Release artifact generation with GoReleaser
92+
- Security scanning and build attestation
93+
94+
**Quick example** for your own repository's `.github/workflows/Release.yml`:
95+
96+
```yaml
97+
name: Release
98+
99+
on:
100+
push:
101+
tags:
102+
- v*
103+
104+
permissions: write-all
105+
106+
jobs:
107+
release:
108+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
109+
with:
110+
registry-name: ghcr.io/yourusername/yourproject
111+
```
112+
113+
### Detailed Documentation
114+
115+
For complete instructions, configuration options, and examples, see:
116+
**[📖 Workflow Reuse Guide](docs/WORKFLOW_REUSE.md)**
117+
118+
This guide covers:
119+
- Configuration options and parameters
120+
- GoReleaser setup requirements
121+
- Container registry configuration
122+
- Troubleshooting and debugging
123+
- Security considerations
124+
125+
**Quick start files:**
126+
- [📋 Example Release Workflow](docs/example-release-workflow.yml) - Copy this to your project's `.github/workflows/Release.yml`
127+
128+
---
129+
81130
## Running the Service
82131

83132
### Cluster Name
@@ -226,7 +275,9 @@ curl -X PUT http://localhost:27777/cloud-init/admin/instance-info/x3000c1b1n1 \
226275

227276
## More Reading
228277

278+
- [Workflow Reuse Guide](docs/WORKFLOW_REUSE.md) - How to use this project's CI/CD workflow in other repositories
229279
- [Official cloud-init documentation](https://cloud-init.io/)
230280
- [OpenCHAMI TPM-manager service](https://github.com/OpenCHAMI/TPM-manager)
231281
- [GoReleaser Documentation](https://goreleaser.com/)
232282
- [SMD Documentation](https://github.com/OpenCHAMI/smd)
283+
- [OpenCHAMI GitHub Actions](https://github.com/OpenCHAMI/github-actions) - Centralized reusable workflows

‎docs/WORKFLOW_REUSE.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Reusing the OpenCHAMI Release Workflow
2+
3+
This document explains how to use the centralized GitHub Actions workflow from the OpenCHAMI cloud-init repository in your own projects.
4+
5+
## Overview
6+
7+
The OpenCHAMI cloud-init project uses a centralized, reusable GitHub Actions workflow that handles:
8+
- Go application building with GoReleaser
9+
- Multi-architecture builds (amd64, arm64)
10+
- Container image creation and publishing
11+
- Release artifact generation
12+
- Build attestation and security scanning
13+
14+
The workflow is centralized in the [OpenCHAMI/github-actions](https://github.com/OpenCHAMI/github-actions) repository and can be reused by any Go project.
15+
16+
## Quick Start
17+
18+
To use this workflow in your own repository, create a `.github/workflows/Release.yml` file:
19+
20+
```yaml
21+
name: Release with goreleaser
22+
23+
on:
24+
workflow_dispatch:
25+
push:
26+
tags:
27+
- v*
28+
29+
permissions: write-all # Necessary for the generate-build-provenance action with containers
30+
31+
jobs:
32+
release:
33+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
34+
with:
35+
cgo-enabled: "1"
36+
pre-build-commands: |
37+
go install github.com/swaggo/swag/cmd/swag@latest
38+
attestation-binary-path: "dist/cloud-init*"
39+
registry-name: ghcr.io/openchami/cloud-init
40+
```
41+
42+
> 💡 **Tip**: You can also copy the [example workflow file](example-release-workflow.yml) and customize it for your project.
43+
44+
## Configuration Options
45+
46+
The reusable workflow accepts several input parameters that you can customize:
47+
48+
### Required Inputs
49+
50+
- `registry-name`: The container registry where images will be pushed (e.g., `ghcr.io/yourusername/yourproject`)
51+
52+
### Optional Inputs
53+
54+
- `cgo-enabled`: Enable or disable CGO compilation (default: "0", set to "1" if needed)
55+
- `pre-build-commands`: Commands to run before building (e.g., code generation, dependency installation)
56+
- `attestation-binary-path`: Glob pattern for binaries to create attestations for
57+
- `go-version`: Go version to use (defaults to latest stable)
58+
- `goreleaser-version`: GoReleaser version to use (defaults to latest)
59+
60+
## Usage Examples
61+
62+
### Basic Go Application
63+
64+
For a simple Go application without special requirements:
65+
66+
```yaml
67+
name: Release
68+
69+
on:
70+
push:
71+
tags:
72+
- v*
73+
74+
permissions: write-all
75+
76+
jobs:
77+
release:
78+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
79+
with:
80+
registry-name: ghcr.io/myorg/myapp
81+
```
82+
83+
### Application with Code Generation
84+
85+
For applications that need code generation (like Swagger docs):
86+
87+
```yaml
88+
name: Release
89+
90+
on:
91+
push:
92+
tags:
93+
- v*
94+
95+
permissions: write-all
96+
97+
jobs:
98+
release:
99+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
100+
with:
101+
cgo-enabled: "0"
102+
pre-build-commands: |
103+
go install github.com/swaggo/swag/cmd/swag@latest
104+
swag init -g cmd/myapp/main.go
105+
registry-name: ghcr.io/myorg/myapp
106+
attestation-binary-path: "dist/myapp*"
107+
```
108+
109+
### Application with CGO Dependencies
110+
111+
For applications that require CGO (C bindings):
112+
113+
```yaml
114+
name: Release
115+
116+
on:
117+
push:
118+
tags:
119+
- v*
120+
121+
permissions: write-all
122+
123+
jobs:
124+
release:
125+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
126+
with:
127+
cgo-enabled: "1"
128+
registry-name: ghcr.io/myorg/myapp
129+
```
130+
131+
## Prerequisites
132+
133+
For the workflow to work properly in your repository, you need:
134+
135+
### 1. GoReleaser Configuration
136+
137+
Create a `.goreleaser.yaml` file in your repository root. You can use the [cloud-init example](./.goreleaser.yaml) as a template:
138+
139+
```yaml
140+
version: 2.4
141+
project_name: your-project-name
142+
143+
before:
144+
hooks:
145+
- go mod tidy
146+
# Add any additional pre-build commands here
147+
148+
builds:
149+
- id: your-app
150+
main: ./cmd/your-app
151+
binary: your-app
152+
ldflags:
153+
- "-X 'main.Version={{.Version}}' -X 'main.GitCommit={{.Commit}}'"
154+
goos:
155+
- linux
156+
- darwin
157+
goarch:
158+
- amd64
159+
- arm64
160+
env:
161+
- CGO_ENABLED=0 # or 1 if you need CGO
162+
163+
# Add docker, archives, and other configurations as needed
164+
```
165+
166+
### 2. Repository Permissions
167+
168+
Ensure your repository has the necessary permissions:
169+
- **Actions**: Enabled for running workflows
170+
- **Packages**: Write permissions for container registry pushes
171+
- **Contents**: Write permissions for creating releases
172+
173+
### 3. Container Registry Setup
174+
175+
If publishing to GitHub Container Registry (ghcr.io):
176+
1. Enable the Package feature in your repository settings
177+
2. Configure package visibility (public/private)
178+
3. The workflow will automatically authenticate using the `GITHUB_TOKEN`
179+
180+
## Environment Variables
181+
182+
The workflow automatically sets these environment variables for GoReleaser:
183+
184+
- `GIT_STATE`: "clean" or "dirty" based on repository state
185+
- `BUILD_HOST`: Hostname of the build machine
186+
- `GO_VERSION`: Go version being used
187+
- `BUILD_USER`: Username performing the build
188+
189+
You can reference these in your `.goreleaser.yaml` file:
190+
191+
```yaml
192+
builds:
193+
- ldflags:
194+
- "-X 'main.GitState={{ .Env.GIT_STATE }}'"
195+
- "-X 'main.BuildHost={{ .Env.BUILD_HOST }}'"
196+
- "-X 'main.GoVersion={{ .Env.GO_VERSION }}'"
197+
- "-X 'main.BuildUser={{ .Env.BUILD_USER }}'"
198+
```
199+
200+
## Triggering Releases
201+
202+
The workflow is typically triggered by:
203+
204+
1. **Tag pushes**: When you push a tag starting with 'v'
205+
```bash
206+
git tag v1.0.0
207+
git push origin v1.0.0
208+
```
209+
210+
2. **Manual dispatch**: Using the GitHub UI or CLI
211+
```bash
212+
gh workflow run Release.yml
213+
```
214+
215+
## Troubleshooting
216+
217+
### Common Issues
218+
219+
1. **GoReleaser version mismatch**: Ensure your local GoReleaser version matches the one used in CI
220+
2. **CGO errors**: Set `cgo-enabled: "1"` if your application uses C dependencies
221+
3. **Permission errors**: Verify repository has write permissions for packages and contents
222+
4. **Registry authentication**: Ensure container registry name matches your organization/username
223+
224+
### Debugging
225+
226+
To debug locally:
227+
228+
1. Install GoReleaser locally
229+
2. Set the required environment variables:
230+
```bash
231+
export GIT_STATE=$(if git diff-index --quiet HEAD --; then echo 'clean'; else echo 'dirty'; fi)
232+
export BUILD_HOST=$(hostname)
233+
export GO_VERSION=$(go version | awk '{print $3}')
234+
export BUILD_USER=$(whoami)
235+
```
236+
3. Run in snapshot mode:
237+
```bash
238+
goreleaser release --snapshot --clean
239+
```
240+
241+
## Security Considerations
242+
243+
The workflow includes security features:
244+
- **Build attestation**: Creates signed attestations for build artifacts
245+
- **Container scanning**: Automatically scans container images for vulnerabilities
246+
- **Secure defaults**: Uses minimal permissions and secure build practices
247+
248+
## More Information
249+
250+
- [OpenCHAMI GitHub Actions Repository](https://github.com/OpenCHAMI/github-actions)
251+
- [GoReleaser Documentation](https://goreleaser.com/)
252+
- [GitHub Actions Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows)

‎docs/example-release-workflow.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Example Release Workflow
2+
# Copy this file to .github/workflows/Release.yml in your Go project
3+
# to use the OpenCHAMI centralized release workflow
4+
5+
name: Release with goreleaser
6+
7+
on:
8+
workflow_dispatch:
9+
push:
10+
tags:
11+
- v*
12+
13+
permissions: write-all # Necessary for the generate-build-provenance action with containers
14+
15+
jobs:
16+
release:
17+
uses: OpenCHAMI/github-actions/workflows/go-build-release.yml@v2
18+
with:
19+
# Configure these parameters for your project:
20+
21+
# Registry where container images will be pushed
22+
registry-name: ghcr.io/yourusername/yourproject
23+
24+
# Enable CGO if your project has C dependencies (default: "0")
25+
cgo-enabled: "0"
26+
27+
# Commands to run before building (optional)
28+
# Example: code generation, installing tools, etc.
29+
pre-build-commands: |
30+
echo "Add your pre-build commands here"
31+
# go install github.com/swaggo/swag/cmd/swag@latest
32+
# swag init -g cmd/yourapp/main.go
33+
34+
# Pattern for binaries to create attestations for (optional)
35+
attestation-binary-path: "dist/yourapp*"
36+
37+
# Additional configuration notes:
38+
# 1. Replace "yourusername/yourproject" with your actual registry path
39+
# 2. Ensure you have a .goreleaser.yaml file in your repository root
40+
# 3. Your repository needs write permissions for packages and contents
41+
# 4. For private registries, you may need additional authentication setup

0 commit comments

Comments
 (0)