Skip to content

Commit 7e2092d

Browse files
huaweic-nvhuaweic-nv
committed
docs: add per-action README files and update main README
Add README.md for go-lint, go-test, license-headers, and commitlint actions following existing project conventions. Update main README with new actions in the available actions table, repository structure tree, and documentation links section. Also includes linter-applied SHA pinning for action refs in docs.
1 parent 4483505 commit 7e2092d

7 files changed

Lines changed: 225 additions & 4 deletions

File tree

‎.github/actions/codeql-scan/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -412,7 +412,7 @@ jobs:
412412
codeql-go:
413413
steps:
414414
- uses: actions/checkout@v4
415-
- uses: actions/setup-go@v5
415+
- uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
416416
- uses: NVIDIA/dsx-github-actions/.github/actions/codeql-scan@main
417417
with:
418418
languages: "go"
@@ -558,7 +558,7 @@ jobs:
558558
build-and-scan:
559559
steps:
560560
- uses: actions/checkout@v4
561-
- uses: actions/setup-go@v5
561+
- uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
562562
563563
# CodeQL will trace this build
564564
- uses: NVIDIA/dsx-github-actions/.github/actions/codeql-scan@main

‎.github/actions/commitlint/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Commitlint Action
2+
3+
A GitHub Composite Action that validates commit messages against [Conventional Commits](https://www.conventionalcommits.org/) using `commitlint`.
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- uses: actions/checkout@v4
10+
with:
11+
fetch-depth: 0 # Required to access commit history
12+
- name: Lint Commits
13+
uses: NVIDIA/dsx-github-actions/.github/actions/commitlint@main
14+
```
15+
16+
### With custom config
17+
18+
```yaml
19+
steps:
20+
- uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
- name: Lint Commits
24+
uses: NVIDIA/dsx-github-actions/.github/actions/commitlint@main
25+
with:
26+
config-file: '.commitlintrc.js'
27+
```
28+
29+
## Inputs
30+
31+
| Input | Description | Required | Default |
32+
| :--- | :--- | :--- | :--- |
33+
| `config-file` | Path to commitlint config file. If empty, uses default discovery. | `false` | `''` |
34+
| `from` | Lint commits starting from this ref (exclusive). | `false` | `''` |
35+
| `to` | Lint commits up to this ref (inclusive). | `false` | `HEAD` |
36+
| `node-version` | Node.js version to use. | `false` | `20` |
37+
38+
## Behavior
39+
40+
1. **Set up Node.js** using `actions/setup-node`.
41+
2. **Install commitlint** packages (`@commitlint/cli` and `@commitlint/config-conventional`).
42+
3. **Determine commit range** automatically:
43+
- If `from` input is provided, uses that ref.
44+
- In PR context: lints commits from the base branch (`origin/$GITHUB_BASE_REF`).
45+
- In push context: lints only the latest commit (`HEAD~1..HEAD`).
46+
- On initial commits or shallow clones: lints `HEAD` only.
47+
4. **Run commitlint** with verbose output.
48+
49+
## Notes
50+
51+
- The calling workflow must use `actions/checkout` with `fetch-depth: 0` (or at least enough depth to cover all commits in the PR) for commitlint to access the full commit range.
52+
- npm packages are installed with `--ignore-scripts` for supply chain safety.

‎.github/actions/go-lint/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Go Lint Action
2+
3+
A GitHub Composite Action that runs a Go linting suite: `golangci-lint`, `go fmt` check, and `go vet`.
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Go Lint
11+
uses: NVIDIA/dsx-github-actions/.github/actions/go-lint@main
12+
with:
13+
working-directory: '.'
14+
```
15+
16+
### With vendor mode and custom config
17+
18+
```yaml
19+
steps:
20+
- uses: actions/checkout@v4
21+
- name: Go Lint
22+
uses: NVIDIA/dsx-github-actions/.github/actions/go-lint@main
23+
with:
24+
go-flags: '-mod=vendor'
25+
config-path: '.golangci.yml'
26+
golangci-lint-args: '--timeout=5m'
27+
```
28+
29+
## Inputs
30+
31+
| Input | Description | Required | Default |
32+
| :--- | :--- | :--- | :--- |
33+
| `go-version` | Go version to use (e.g., `1.25.5`). If empty, uses `go.mod`. | `false` | `''` |
34+
| `go-version-file` | Path to `go.mod` for version detection. | `false` | `go.mod` |
35+
| `working-directory` | Working directory for lint commands. | `false` | `.` |
36+
| `golangci-lint-version` | golangci-lint version. | `false` | `v2.11` |
37+
| `golangci-lint-args` | Additional arguments for `golangci-lint run`. | `false` | `''` |
38+
| `config-path` | Path to `.golangci.yml` config file. | `false` | `''` |
39+
| `go-flags` | `GOFLAGS` environment variable (e.g., `-mod=vendor`). | `false` | `''` |
40+
41+
## Behavior
42+
43+
1. **Set up Go** using `actions/setup-go` with caching enabled.
44+
2. **Check go fmt** by running `gofmt -l` on all `.go` files (excluding `vendor/`). Fails if any files are unformatted.
45+
3. **Run go vet** on all packages.
46+
4. **Run golangci-lint** via `golangci/golangci-lint-action`.

‎.github/actions/go-test/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Go Test Action
2+
3+
A GitHub Composite Action that runs Go tests with race detection, coverage reporting, and JUnit XML output via `gotestsum`.
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Go Test
11+
uses: NVIDIA/dsx-github-actions/.github/actions/go-test@main
12+
```
13+
14+
### With custom packages and flags
15+
16+
```yaml
17+
steps:
18+
- uses: actions/checkout@v4
19+
- name: Go Test
20+
uses: NVIDIA/dsx-github-actions/.github/actions/go-test@main
21+
with:
22+
packages: './pkg/...'
23+
test-flags: '-v -count=1 -timeout=10m'
24+
go-flags: '-mod=vendor'
25+
artifact-name: 'test-results-${{ matrix.go-version }}'
26+
```
27+
28+
## Inputs
29+
30+
| Input | Description | Required | Default |
31+
| :--- | :--- | :--- | :--- |
32+
| `go-version` | Go version to use (e.g., `1.25.5`). If empty, uses `go.mod`. | `false` | `''` |
33+
| `go-version-file` | Path to `go.mod` for version detection. | `false` | `go.mod` |
34+
| `working-directory` | Working directory for running tests. | `false` | `.` |
35+
| `packages` | Go packages to test. | `false` | `./...` |
36+
| `race` | Enable race detector. | `false` | `true` |
37+
| `coverage` | Enable coverage reporting. | `false` | `true` |
38+
| `coverage-file` | Coverage output file name. | `false` | `coverage.out` |
39+
| `junit` | Generate JUnit XML report via `gotestsum`. | `false` | `true` |
40+
| `junit-file` | JUnit XML output file name. | `false` | `junit-report.xml` |
41+
| `test-flags` | Additional flags passed to `go test`. | `false` | `-v -count=1` |
42+
| `go-flags` | `GOFLAGS` environment variable (e.g., `-mod=vendor`). | `false` | `''` |
43+
| `gotestsum-version` | `gotestsum` version to install. | `false` | `v1.12.0` |
44+
| `upload-artifacts` | Upload coverage and JUnit reports as workflow artifacts. | `false` | `true` |
45+
| `artifact-name` | Name for uploaded artifact (override to avoid collisions in matrix builds). | `false` | `go-test-results` |
46+
47+
## Outputs
48+
49+
| Output | Description |
50+
| :--- | :--- |
51+
| `coverage-file` | Path to coverage output file. |
52+
| `junit-file` | Path to JUnit XML report. |
53+
54+
## Behavior
55+
56+
1. **Set up Go** using `actions/setup-go` with caching enabled.
57+
2. **Install gotestsum** (pinned version) if JUnit output is enabled.
58+
3. **Run tests** with configurable race detection, coverage, and JUnit output.
59+
4. **Display coverage summary** showing the total coverage percentage.
60+
5. **Upload artifacts** (coverage and JUnit reports) with 7-day retention.
61+
62+
## Notes
63+
64+
- When using matrix builds, set `artifact-name` to a unique value per matrix cell to avoid upload collisions (e.g., `artifact-name: 'test-results-${{ matrix.go-version }}'`).
65+
- All shell inputs are routed through environment variables to prevent expression injection.

‎.github/actions/license-headers/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# License Headers Action
2+
3+
A GitHub Composite Action that checks (and optionally adds) SPDX license headers using `addlicense`.
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Check License Headers
11+
uses: NVIDIA/dsx-github-actions/.github/actions/license-headers@main
12+
```
13+
14+
### Auto-add missing headers
15+
16+
```yaml
17+
steps:
18+
- uses: actions/checkout@v4
19+
- name: Add License Headers
20+
uses: NVIDIA/dsx-github-actions/.github/actions/license-headers@main
21+
with:
22+
check-only: 'false'
23+
paths: 'src/ pkg/ cmd/'
24+
ignore: 'vendor/**,testdata/**'
25+
```
26+
27+
## Inputs
28+
29+
| Input | Description | Required | Default |
30+
| :--- | :--- | :--- | :--- |
31+
| `license` | License type (`apache`, `mit`, `bsd`). | `false` | `apache` |
32+
| `copyright-holder` | Copyright holder string. | `false` | `NVIDIA CORPORATION & AFFILIATES. All rights reserved.` |
33+
| `year` | Copyright year. | `false` | `2026` |
34+
| `paths` | Space-separated paths to check. | `false` | `.` |
35+
| `ignore` | Comma-separated glob patterns to ignore. | `false` | `vendor/**` |
36+
| `check-only` | Only check headers (fail if missing). Set to `false` to auto-add. | `false` | `true` |
37+
| `addlicense-version` | `addlicense` tool version. | `false` | `v1.2.0` |
38+
| `go-version` | Go version for installing `addlicense`. If empty, uses existing Go. | `false` | `''` |
39+
40+
## Behavior
41+
42+
1. **Set up Go** (optional, only if `go-version` is specified).
43+
2. **Install addlicense** at the pinned version.
44+
3. **Check or add** license headers depending on the `check-only` flag.
45+
- Check mode: fails if any files are missing headers.
46+
- Add mode: automatically inserts missing headers.

‎.github/actions/semantic-release/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ steps:
291291
### Example 7: NPM Package Publishing
292292
293293
```yaml
294-
- uses: actions/setup-node@v4
294+
- uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
295295
with:
296296
node-version: "20"
297297

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ A collection of reusable GitHub Actions for standardizing CI/CD workflows across
1313
| [docker-build](.github/actions/docker-build/) | Docker Buildx build/push wrapper | Build/push multi-arch OCI images |
1414
| [git-tag](.github/actions/git-tag/) | Create and push git tag | Tagging releases |
1515
| [slack-notify](.github/actions/slack-notify/) | Send notifications to Slack | CI/CD status notifications |
16+
| [go-lint](.github/actions/go-lint/) | Go linting (golangci-lint, fmt, vet) | Go code quality checks |
17+
| [go-test](.github/actions/go-test/) | Go tests with coverage and JUnit | Go test execution and reporting |
18+
| [license-headers](.github/actions/license-headers/) | SPDX license header checks | License compliance |
19+
| [commitlint](.github/actions/commitlint/) | Conventional commit validation | Commit message enforcement |
1620

1721
## ♻️ Available Workflows
1822

@@ -107,6 +111,10 @@ This reusable workflow wraps `skopeo copy`, so it copies the entire manifest lis
107111
- [Resource Push NGC Action](.github/actions/resource-push-ngc/README.md)
108112
- [Docker Build Action](.github/actions/docker-build/README.md)
109113
- [Slack Notify Action](.github/actions/slack-notify/README.md)
114+
- [Go Lint Action](.github/actions/go-lint/README.md)
115+
- [Go Test Action](.github/actions/go-test/README.md)
116+
- [License Headers Action](.github/actions/license-headers/README.md)
117+
- [Commitlint Action](.github/actions/commitlint/README.md)
110118
- [Workflows Guide](.github/workflows/README.md)
111119

112120
## 🎯 Features
@@ -309,7 +317,11 @@ If CI still fails, execute `pre-commit run actionlint --all-files` or `pre-commi
309317
│ ├── semantic-release/ # Automated versioning and releases
310318
│ ├── resource-push-ngc/ # NGC resources publishing
311319
│ ├── git-tag/ # Create and push git tag
312-
│ └── slack-notify/ # Send Slack notifications
320+
│ ├── slack-notify/ # Send Slack notifications
321+
│ ├── go-lint/ # Go linting (golangci-lint, fmt, vet)
322+
│ ├── go-test/ # Go tests with coverage and JUnit
323+
│ ├── license-headers/ # SPDX license header checks
324+
│ └── commitlint/ # Conventional commit validation
313325
└── workflows/
314326
├── release.yml # Automatic semantic versioning
315327
├── promote-image.yml # Promote image across registries

0 commit comments

Comments
 (0)