@smbcloud / smbcloud-deploy-action
Code Commits Issues Pulls Cloud Agent CI/CD
main
main
md 118 lines 4.12 KB
Rendered Raw
1 # Contributing to smbcloud-deploy-action
2
3 Thank you for considering contributing! This is a [composite GitHub Action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action).
4 The whole thing is `action.yml` plus the bash it runs and the docs around it. There's no build step and no compiler.
5
6 ## Code of Conduct
7
8 By participating in this project you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please be respectful and considerate of others.
9
10 ## Prerequisites
11
12 - A POSIX shell with `bash` (the action's steps are `shell: bash`).
13 - [`actionlint`](https://github.com/rhysd/actionlint) lints workflow and action YAML.
14 - [`shellcheck`](https://www.shellcheck.net/) lints the bash inside the steps (actionlint runs it for you when installed).
15 - [`yq`](https://github.com/mikefarah/yq) or any YAML parser, for a quick syntax check.
16
17 ## Getting Started
18
19 1. Fork the repository on GitHub.
20 2. Clone your fork:
21 ```sh
22 git clone https://github.com/your-username/smbcloud-deploy-action.git
23 cd smbcloud-deploy-action
24 ```
25 3. Create a branch for your work:
26 ```sh
27 git checkout -b your-feature-or-fix
28 ```
29
30 ## Development Workflow
31
32 ### Validate `action.yml`
33
34 Confirm the YAML parses and lint the embedded shell:
35
36 ```sh
37 # YAML parses
38 python3 -c "import yaml; yaml.safe_load(open('action.yml'))"
39
40 # Lint the action and its embedded bash (runs shellcheck under the hood)
41 actionlint
42 ```
43
44 ### Test it end to end
45
46 The only real test is running the action in a workflow. Add or update an example
47 workflow under `.github/workflows/` (or test from a throwaway repo) and trigger a
48 deploy against a disposable smbCloud project. Verify:
49
50 - the correct release binary is downloaded for the runner OS/arch,
51 - the token lands in the right state dir (`.smb` for production, `.smb-dev` for dev),
52 - a failed `smb deploy` fails the job (non-zero exit propagates).
53
54 ## Coding Guidelines
55
56 These rules are enforced in code review:
57
58 - Keep every step `shell: bash` and start scripts with `set -euo pipefail`.
59 - Pass inputs into steps via `env:` and reference them as `"${INPUT_NAME}"`. Do
60 **not** interpolate `${{ inputs.* }}` directly inside a `run:` block, since that
61 invites shell injection. The action already follows this pattern; keep it.
62 - Quote all variable expansions.
63 - Fail fast with `echo "::error::..."` and a non-zero exit on bad input.
64 - Never log secret values. Token and key contents must not be echoed.
65 - Keep the action generic: no server hostnames, account/user IDs, real customer
66 domains, project IDs, or other smbCloud fleet detail. Use placeholders
67 (`example.com`, `<user-id>`, `<app>`) in docs and examples.
68
69 ## Submitting a Pull Request
70
71 1. Ensure the YAML parses and `actionlint` is clean before pushing.
72 2. Update `README.md` if you add, rename, or change an input or output.
73 3. Push your branch and open a PR against `main`.
74 4. A maintainer will review your changes and may request modifications.
75
76 ### PR Title Convention
77
78 Use a clear, imperative title that describes the change:
79
80 - ✅ `Add support for arm64 runners`
81 - ✅ `Fail fast when ssh-key-name is missing`
82 - ❌ `feat: add arm64` (no conventional-commit prefixes)
83 - ❌ `Fixed some stuff.` (no past tense, no trailing punctuation)
84
85 ## Releasing
86
87 Releases are handled by maintainers via Git tags. Cut a version tag and move the
88 floating major tag so consumers pinning `@v1` get the update:
89
90 ```sh
91 git tag -a v1.2.0 -m "v1.2.0"
92 git tag -f v1 v1.2.0
93 git push origin v1.2.0
94 git push -f origin v1
95 ```
96
97 ## Reporting Bugs
98
99 Use the GitHub issue tracker and fill out the bug report template. Please include:
100
101 - A clear description of the problem.
102 - A minimal workflow snippet that reproduces it.
103 - The runner OS, the action version (tag/SHA), and the resolved CLI version.
104 - Expected vs. actual behaviour.
105
106 ## Requesting Features
107
108 Use the GitHub issue tracker and fill out the feature request template. Describe
109 the use case clearly: what problem does the feature solve?
110
111 ## Security
112
113 Please report security vulnerabilities privately. See [SECURITY.md](SECURITY.md).
114 Do not open a public issue for security reports.
115
116 ## Questions?
117
118 Open a GitHub issue or reach out to the maintainers. We're happy to help.