Skip to content

Commit b076716

Browse files
mrcjkbmrcjkb
authored
docs: add github action (#17)
1 parent c07afaa commit b076716

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎docs/tutorial/09-ci-cd.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
id: cicd
3+
title: Automating tests and releases
4+
---
5+
6+
Continuous integration and deployment (CI/CD) allows us to automatically run tests against external
7+
contributions and upload our package whenever we publish a release.
8+
In this chapter, we'll learn how to set up the [Lux GitHub Action](TODO).
9+
10+
:::note
11+
We plan on creating integrations for other CI/CD platforms, too.
12+
For now, you can use [Nix](https://nixos.org/) or an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers)
13+
to install Lux on other platforms.
14+
:::
15+
16+
## Running tests
17+
18+
So far, we've been developing and testing on our host platform.
19+
But our users might be using other platforms. To make sure our application works for them,
20+
we can run tests using GitHub Actions.
21+
22+
First, create a `.github/workflows` directory in the root of your project.
23+
In that directory, add a `tests.yml` file with the following content:
24+
25+
```yaml
26+
---
27+
name: Lux
28+
on:
29+
pull_request:
30+
push:
31+
branches: [main]
32+
33+
jobs:
34+
lux-action:
35+
name: ${{ matrix.job.target }} - Lua ${{ matrix.lua_version }}
36+
runs-on: ${{ matrix.job.os }}
37+
strategy:
38+
fail-fast: false
39+
matrix:
40+
job:
41+
- { os: ubuntu-24.04, target: x86_64-linux }
42+
- { os: ubuntu-24.04-arm, target: aarch64-linux }
43+
- { os: macos-14, target: aarch64-darwin }
44+
- { os: windows-2025, target: x86_63-windows-msvc }
45+
lua_version:
46+
- 5.1
47+
- 5.2
48+
- 5.3
49+
- 5.4
50+
steps:
51+
- name: Checkout repository
52+
uses: actions/checkout@v5
53+
54+
- name: Install MSVC Compiler Toolchain
55+
uses: ilammy/msvc-dev-cmd@v1
56+
if: endsWith(matrix.job.target, '-msvc')
57+
58+
- name: Install Lux
59+
uses: lumen-oss/gh-actions-lux@v1
60+
with:
61+
version: 0.18.8
62+
63+
- name: Run tests
64+
run: |
65+
lx --lua-version ${{ matrix.lua_version }} test
66+
```
67+
68+
This workflow will run
69+
70+
- On each pull request.
71+
- Whenever someone pushes to the `main` branch.
72+
73+
It runs on Linux (x86_64 + aarch64 architecures), macOS (aarch64) and Windows (x86_64),
74+
once for each Lua version from 5.1 to 5.4.
75+
76+
:::important
77+
For reproducibility, we recommend pinning the Lux version with the `version` input.
78+
This will prevent your workflow from breaking if we release a new version of Lux with a breaking change.
79+
:::
80+
81+
## Automating releases
82+
83+
### Installing release-please
84+
85+
Because of the way we'll be setting up the workflow later on, it is recommended that you install [`release-please`](https://github.com/googleapis/release-please-action),
86+
a tool that automates the semver process.
87+
All you do is write commits in the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
88+
style (for example `fix: annoying bug` or `feat(ui): add new buttons`) and release-please generates
89+
a new release version in the form of a pull request to your repository.
90+
91+
:::note
92+
The pull request made by the Github action gets updated on every new commit that you make - this means you control
93+
when a new version of your package is published by **merging the pull request**.
94+
95+
When you do this, a new tag and release will be created on your repository, which is a critical step.
96+
:::
97+
98+
In your repository root, create a file under `.github/workflows/release-please.yml`.
99+
Paste the following contents into the file:
100+
101+
```yaml
102+
---
103+
name: Release Please
104+
105+
on:
106+
push:
107+
branches: [main]
108+
workflow_dispatch: # Enables manual triggers
109+
110+
permissions:
111+
contents: write
112+
pull-requests: write
113+
114+
jobs:
115+
release:
116+
name: release
117+
runs-on: ubuntu-latest
118+
steps:
119+
- uses: googleapis/release-please-action@v4
120+
with:
121+
token: ${{ secrets.PAT }}
122+
release-type: simple
123+
```
124+
125+
Note that we pass in a `${{ secrets.PAT }}` repository secret via the `token` input,
126+
which we'll need to generate.
127+
This will allow the "publish" workflow (which we'll set up next) to be triggered by the
128+
release-please workflow.
129+
The process is quite simple, so let's get it over with.
130+
131+
### Generating a PAT (Personal Access Token)
132+
133+
134+
1. Navigate to your Account -> Settings.
135+
136+
![settings](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/52cce7d0-b53c-467f-a3d9-a1bd6a1e1614)
137+
138+
2. Navigate to the "Developer Settings" tab on the very bottom of the Settings tab.
139+
140+
![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/0452ab2a-3f2f-4162-a8f4-411ba6bd2f37)
141+
142+
3. Make your way over to Personal Access Tokens -> Tokens (classic). We won't need fine-grained tokens for this simple task.
143+
144+
![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/863a5358-551c-4f44-b31b-85bb906cbc21)
145+
146+
4. Generate a new classic token.
147+
148+
![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/72693b75-1a65-4bb7-8e01-bb256aa4db15)
149+
150+
5. Modify the highlighted sections to the values shown on screen.
151+
152+
![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/534f49a0-d46d-422e-9c29-92d6f54dd640)
153+
154+
6. Press "Generate Token"!
155+
156+
7. **Copy your PAT to the same place where you stored your LuaRocks API key in the previous tutorial**. Make sure it's somewhere safe!
157+
158+
![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/46c8d326-5534-447e-9268-670b872e3144)
159+
160+
161+
### Publishing to LuaRocks
162+
163+
After your repository has a working versioning scheme we may now move on to actually publishing
164+
our package to luarocks.
165+
166+
It is recommended that your repository has as much metadata as possible (a license that is detected by github on the right side of your package's page, a repo title/description, github topics etc.) in your Github repository.
167+
168+
Time to add our API key!
169+
170+
### Adding our API Key and PAT
171+
172+
1. Navigate to your Github repository and enter its settings.
173+
174+
![image](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/3fab5791-189f-42cb-b8b2-824af45a114d)
175+
176+
2. In the settings go to `Security > Secrets and variables > Actions`.
177+
178+
![image](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/ab8ca077-3f8a-4263-9583-2abcebdf9e6a)
179+
180+
3. Click `New repository secret`, almost there!
181+
182+
![image](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/a67ddd29-5021-4d45-ae74-8a40507ccc51)
183+
4. Name the secret `LUX_API_KEY` (make sure it's spelled exactly like this!). In the `Secret` field paste
184+
the API key you copied from the first step of the tutorial.
185+
186+
![image](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/48590516-cf03-43a4-9ded-575c5a63caf5)
187+
188+
Click `Add secret` and there you go! This secret is only visible to you (the
189+
repo owner) and administrators of your repository, so don't be afraid of anyone using it without your consent!
190+
191+
:::important
192+
If you also set up `release-please` earlier in the tutorial, create *another* secret called `PAT` (make sure it's called
193+
exactly like this!). In the `Secret` field paste in your **Github Personal Access Token** that you copied earlier.
194+
:::
195+
196+
### Publishing to LuaRocks
197+
198+
Similarly to the `release-please` setup process, create a `.github/workflows/publish.yml` file from the root of your repo.
199+
200+
Paste the following into the file:
201+
202+
```yaml
203+
---
204+
name: Lux upload
205+
on:
206+
push:
207+
tags: # Will upload to luarocks.org when a tag is pushed
208+
- "*"
209+
workflow_dispatch:
210+
jobs:
211+
luarocks-upload:
212+
runs-on: ubuntu-22.04
213+
steps:
214+
- name: Checkout repository
215+
uses: actions/checkout@v5
216+
217+
- name: Install Lux
218+
uses: lumen-oss/gh-actions-lux@v1
219+
with:
220+
version: 0.18.8
221+
222+
- name: Upload
223+
run: |
224+
lx upload
225+
env:
226+
LUX_API_KEY: ${{ secrets.LUX_API_KEY }}
227+
```
228+
229+
## Publish a Release of your package
230+
231+
Now that we have everything set up, all the pieces can fall into place.
232+
Go to the Pull Requests tab in your repository where `release-please` should have created a PR for you
233+
(assuming your were using conventional commits). Merge that pull request, and the chain reaction should begin!
234+
First, release-please should (after a minute or so) publish a new tag with a version. Afterwards, the "publish"
235+
workflow should trigger and your package should end up on `luarocks.org`!
236+
237+
## Troubleshooting
238+
239+
### I already merged the release-please PR earlier!
240+
241+
If you merged your PR beforehand, don't worry. We'll need to install the `gh` CLI tool in order to run
242+
the workflow manually. There are many resources for that online, just search "setting up the gh cli tool" in
243+
your favourite search engine! After you are logged in, run `gh workflow run publish.yml`.
244+
After a minute you should see your package on luarocks :D

0 commit comments

Comments
 (0)