Skip to content

Commit 6ffdc1d

Browse files
Stensel8Stensel8
authored
content: maintain docs about yubikey situation (#32)
## Summary Maintaining some docs, because I changed my Yubikey setup and wanted to share it. ## Type of change <!-- Check all that apply --> - [x] `content` — update or improve existing content - [x] `chore` — maintenance (dependencies, config, CI/CD) ## Checklist - [x] PR title follows the commit convention (e.g. `fix: correct nmcli command in eduroam guide`) - [x] Both EN and NL versions updated (if applicable) - [x] Media is in AVIF format (not PNG/JPG) - [x] No broken image references (`/images/*.avif` all exist in `static/images/`) - [x] Tested locally with `hugo server`
1 parent e86c259 commit 6ffdc1d

13 files changed

Lines changed: 446 additions & 137 deletions

‎.github/pull_request_template.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
- [ ] `refactor` — restructuring without content changes
1515
- [ ] `style` — formatting, whitespace, typos
1616

17+
> [PR title and commit types must follow these standards — view the contributing guide](https://github.com/Stensel8/Zephyrus-Linux/blob/main/CONTRIBUTING.md#commit-messages)
18+
1719
## Checklist
1820

1921
- [ ] PR title follows the commit convention (e.g. `fix: correct nmcli command in eduroam guide`)

‎.github/workflows/convert-images.yml‎

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎.github/workflows/pr-checks.yml‎

Lines changed: 117 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ on:
44
pull_request:
55
branches: [main, development]
66

7+
permissions:
8+
contents: read
9+
pull-requests: write
10+
711
jobs:
812

913
# ── 1. PR title follows conventional commits ────────────────────────────────
@@ -54,15 +58,70 @@ jobs:
5458
runs-on: ubuntu-latest
5559
steps:
5660
- uses: actions/checkout@v6
57-
- name: Check for non-AVIF images
61+
62+
- name: Find non-AVIF images
63+
id: check
5864
run: |
59-
bad=$(find static/images -type f \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" \))
60-
if [ -n "$bad" ]; then
61-
echo "::error::Non-AVIF images found — convert them with avifenc before submitting:"
62-
echo "$bad"
63-
exit 1
65+
{
66+
echo "files<<EOF"
67+
find static/images -type f \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" \) | sort
68+
echo "EOF"
69+
} >> "$GITHUB_OUTPUT"
70+
71+
count=$(find static/images -type f \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" \) | wc -l)
72+
if [ "$count" -gt 0 ]; then
73+
echo "found=true" >> "$GITHUB_OUTPUT"
74+
else
75+
echo "found=false" >> "$GITHUB_OUTPUT"
76+
echo "All images are AVIF."
6477
fi
65-
echo "All images are AVIF."
78+
79+
- name: Post PR comment
80+
if: steps.check.outputs.found == 'true'
81+
uses: actions/github-script@v7
82+
env:
83+
FILES: ${{ steps.check.outputs.files }}
84+
ACTOR: ${{ github.event.pull_request.user.login }}
85+
with:
86+
script: |
87+
const files = process.env.FILES.trim().split('\n').map(f => `- \`${f}\``).join('\n');
88+
const actor = process.env.ACTOR;
89+
const body = [
90+
`Hey @${actor}, looks like you forgot something!`,
91+
'',
92+
'The following images in `static/images/` are not in AVIF format:',
93+
files,
94+
'',
95+
'Please convert them before merging. Install `avifenc` first:',
96+
'```bash',
97+
'sudo pacman -S libavif',
98+
'```',
99+
'',
100+
'Then batch-convert all images in `static/images/`:',
101+
'```bash',
102+
'cd static/images',
103+
'for f in *.png *.jpg *.jpeg; do',
104+
' [ -f "$f" ] && avifenc -q 80 -s 6 "$f" "${f%.*}.avif" && rm "$f"',
105+
'done',
106+
'```',
107+
].join('\n');
108+
109+
await github.rest.issues.createComment({
110+
owner: context.repo.owner,
111+
repo: context.repo.repo,
112+
issue_number: context.payload.pull_request.number,
113+
body,
114+
});
115+
116+
- name: Annotate and fail
117+
if: steps.check.outputs.found == 'true'
118+
env:
119+
FILES: ${{ steps.check.outputs.files }}
120+
run: |
121+
while IFS= read -r f; do
122+
echo "::error file=$f::Convert to AVIF before merging (see README → Image assets)"
123+
done <<< "$FILES"
124+
exit 1
66125
67126
# ── 5. Both EN and NL files present ─────────────────────────────────────────
68127
bilingual:
@@ -136,3 +195,54 @@ jobs:
136195
--root-dir ./public
137196
public/**/*.html
138197
fail: true
198+
199+
# ── 8. Auto-tick PR checklist ────────────────────────────────────────────────
200+
update-checklist:
201+
name: Update PR checklist
202+
runs-on: ubuntu-latest
203+
if: always()
204+
needs: [pr-title, bilingual, image-format, hugo-build, link-check]
205+
steps:
206+
- uses: actions/github-script@v7
207+
env:
208+
RESULT_PR_TITLE: ${{ needs.pr-title.result }}
209+
RESULT_BILINGUAL: ${{ needs.bilingual.result }}
210+
RESULT_IMAGE_FORMAT: ${{ needs.image-format.result }}
211+
RESULT_HUGO_BUILD: ${{ needs.hugo-build.result }}
212+
RESULT_LINK_CHECK: ${{ needs.link-check.result }}
213+
with:
214+
script: |
215+
const { data: pr } = await github.rest.pulls.get({
216+
owner: context.repo.owner,
217+
repo: context.repo.repo,
218+
pull_number: context.payload.pull_request.number,
219+
});
220+
221+
let body = pr.body || '';
222+
223+
// ── Tick checklist items based on CI results ──────────────────────
224+
const setCheck = (keyword, passed) => {
225+
body = body.replace(
226+
new RegExp(`- \\[[ xX]\\] (.*${keyword}.*)`, 'i'),
227+
`- [${passed ? 'x' : ' '}] $1`
228+
);
229+
};
230+
231+
setCheck('PR title follows', process.env.RESULT_PR_TITLE === 'success');
232+
setCheck('Both EN and NL', process.env.RESULT_BILINGUAL === 'success');
233+
setCheck('Media is in AVIF', process.env.RESULT_IMAGE_FORMAT === 'success');
234+
setCheck('No broken image', process.env.RESULT_LINK_CHECK === 'success');
235+
setCheck('Tested locally', process.env.RESULT_HUGO_BUILD === 'success');
236+
237+
// ── Remove unchecked "Type of change" options ─────────────────────
238+
body = body.replace(/^- \[ \] `\w+` —[^\n]*\n?/gm, '');
239+
240+
// ── Collapse leftover blank lines ─────────────────────────────────
241+
body = body.replace(/\n{3,}/g, '\n\n');
242+
243+
await github.rest.pulls.update({
244+
owner: context.repo.owner,
245+
repo: context.repo.repo,
246+
pull_number: context.payload.pull_request.number,
247+
body,
248+
});

‎.markdownlint.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,11 @@ MD022: false
4545
# h1/h2 are rendered by the theme template, not the content file
4646
MD001: false
4747

48+
# Duplicate headings — only flag duplicates within the same section, not across
49+
# different top-level sections (e.g. two separate "### Install" blocks are fine)
50+
MD024:
51+
siblings_only: true
52+
4853
# Table column style (pipe spacing/alignment) — overly pedantic, tables render
4954
# correctly regardless of exact pipe spacing
5055
MD060: false

‎content/docs/known-issues.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Central reference for hardware and software issues on the ASUS ROG Zephyrus G16
88

99
## Active Issues
1010

11+
> These are issues I'm personally still running into. In some cases it might be a real bug; in others it might just be something I'm missing or doing wrong. I'm sharing what I observed, not what I've definitively diagnosed.
12+
1113
### WinBoat: container fails to start
1214

1315
**What's happening:**
@@ -54,6 +56,20 @@ Lowering the global `scroll-factor` in [libinput-config]({{< relref "/docs/appli
5456

5557
---
5658

59+
### YubiKey FIDO2 LUKS unlock: USB timing race
60+
61+
**What's happening:**
62+
Enrolling the YubiKey as a FIDO2 LUKS unlock key succeeds, but at boot `systemd-cryptsetup` fails with `FIDO_ERR_RX`. The key is physically present but seemingly not yet initialized by the USB HID stack when the query comes in. This seems to hit especially on warm reboots.
63+
64+
Tried with `token-timeout=30` in crypttab and `rd.udev.settle-timeout=10` as a kernel parameter, both on systemd 259. Neither helped.
65+
66+
**Status:**
67+
Still unresolved. Not sure if this is a real hardware/firmware timing issue, something specific to this machine, or a misconfiguration on my end. Possibly revisiting later. For now, the YubiKey is used for `sudo` and the GNOME lock screen instead.
68+
69+
See the [YubiKey page]({{< relref "/docs/security/yubikey" >}}) for the full attempted setup and what was reverted.
70+
71+
---
72+
5773
## Resolved Issues
5874

5975
The following issues are resolved. Each entry is either fixed by the Linux kernel developers (notably the AMD GPU page fault bugs in 6.18 and the asus-armoury driver merged in 6.19), or resolved through a configuration workaround I applied myself. Kept here as reference.

‎content/docs/known-issues.nl.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Centrale referentie voor hardware- en softwareproblemen op de ASUS ROG Zephyrus
88

99
## Actieve Problemen
1010

11+
> Dit zijn problemen waar ik persoonlijk nog steeds tegenaan loop. In sommige gevallen is het mogelijk een echte bug; in andere gevallen doe ik misschien zelf iets fout of heb ik iets over het hoofd gezien. Ik deel wat ik heb waargenomen, niet wat ik definitief heb vastgesteld.
12+
1113
### WinBoat: container start niet op
1214

1315
**Wat er gebeurt:**
@@ -54,6 +56,20 @@ Het verlagen van de globale `scroll-factor` in [libinput-config]({{< relref "/do
5456

5557
---
5658

59+
### YubiKey FIDO2 LUKS ontgrendeling: USB timing race
60+
61+
**Wat er gebeurt:**
62+
Het inschrijven van de YubiKey als FIDO2 LUKS-ontgrendelsleutel lukt, maar bij het opstarten geeft `systemd-cryptsetup` `FIDO_ERR_RX` terug. De key is fysiek aanwezig maar lijkt nog niet geïnitialiseerd te zijn door de USB HID-stack op het moment van de query. Dit lijkt met name op te treden bij warme reboots.
63+
64+
Geprobeerd met `token-timeout=30` in crypttab en `rd.udev.settle-timeout=10` als kernelparameter, beide op systemd 259. Geen van beide hielp.
65+
66+
**Status:**
67+
Nog steeds onopgelost. Onduidelijk of dit een echt hardware/firmware timingprobleem is, iets specifiek voor dit apparaat, of een configuratiefout van mijn kant. Mogelijk later nog een keer opgepakt. Voorlopig gebruik ik de YubiKey voor `sudo` en de GNOME-schermvergrendeling.
68+
69+
Zie de [YubiKey-pagina]({{< relref "/docs/security/yubikey" >}}) voor de volledige beschrijving van wat geprobeerd is en wat teruggedraaid is.
70+
71+
---
72+
5773
## Opgeloste Problemen
5874

5975
De volgende problemen zijn opgelost. Elk is ofwel verholpen door de Linux kernel-ontwikkelaars (met name de AMD GPU page fault-bugs in 6.18 en de asus-armoury driver die is samengevoegd in 6.19), of opgelost via een configuratiewijziging die ik zelf heb toegepast. Bewaard als naslagwerk.

0 commit comments

Comments
 (0)