fix: Fixes lychee version and adds CICD support (#295)

* fix: Fixes lychee version and adds CICD support

- Fix pre-commit autoupdate reverting lychee to mutable 'nightly' ref
- Exclude lychee from Makefile and CI autoupdate (non-standard tags)
- Add .secrets support for ACT GitHub token authentication
- Update developer docs with pre-commit hooks and ACT setup guide

* fix: lychee execution in the GitHub Action has errors

Those errors are
```
## Errors per input

### Errors in docs/Bitvavo.md

* [403] <https://bitvavo.com/en/> | Rejected status code (this depends on your "accept" configuration): Forbidden
* [403] <https://bitvavo.com/en/markets> | Rejected status code (this depends on your "accept" configuration): Forbidden
* [403] <https://support.bitvavo.com/hc/en-us> | Rejected status code (this depends on your "accept" configuration): Forbidden

### Errors in docs/DEGIRO.md

* [503] <https://www.degiro.com/> | Rejected status code (this depends on your "accept" configuration): Service Unavailable
* [503] <https://www.degiro.nl/helpdesk/> | Rejected status code (this depends on your "accept" configuration): Service Unavailable
```
But those work locally. The issue may be due to rate limiting or network restrictions.

We will ignore it so far and look into detail in the future.

Author: ctasada

.github/workflows/cicd.yml

@@ -23,6 +23,12 @@ jobs:
       - name: Markdown Check
         run: |
           make markdown-check
+      - name: Check links in Markdown files
+        if: ${{ !env.ACT }}
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --config lychee.toml README.md CHANGELOG.md docs/
+          fail: false  # Don't fail build on broken links (external sites can be flaky)
 
   test:
     name: Tests

.github/workflows/precommit-autoupdate.yml

@@ -19,7 +19,10 @@ jobs:
       - name: Install pre-commit
         run: pip install pre-commit
       - name: Run pre-commit autoupdate script
-        run: pre-commit autoupdate
+        run: |
+          # Run autoupdate but exclude lychee (uses non-standard tag format)
+          pre-commit autoupdate --repo https://github.com/pre-commit/pre-commit-hooks
+          pre-commit autoupdate --repo https://github.com/astral-sh/ruff-pre-commit
       - name: Check for changes
         id: check-changes
         run: |

.gitignore

@@ -69,6 +69,8 @@ config/*
 
 # nektos/act
 .actrc
+# ACT secrets
+.secrets
 
 # lycheecache (Markdown Link Checker)
 .lycheecache

.pre-commit-config.yaml

@@ -37,7 +37,7 @@ repos:
         stages: [pre-commit]
 
   - repo: https://github.com/lycheeverse/lychee
-    rev: nightly
+    rev: lychee-v0.22.0  # Not auto-updated
     hooks:
       - id: lychee
         name: Check Markdown Links

.secrets.example

@@ -0,0 +1,5 @@
+# ACT secrets file
+# Copy this file to .secrets and fill in your GitHub Personal Access Token
+# Generate a token at: https://github.com/settings/tokens
+# Required scope: public_repo (for public repositories)
+GITHUB_TOKEN=your_github_token_here

Makefile

@@ -374,20 +374,28 @@ pre-commit-run: ## Run pre-commit hooks on all files
 
 pre-commit-update: ## Update pre-commit hook versions
 	@echo -e "$(BOLD)$(YELLOW)Updating pre-commit hooks...$(RESET)"
-	poetry run pre-commit autoupdate
+	@echo -e "$(BOLD)$(BLUE)Note: Excluding lychee (uses non-standard tag format)$(RESET)"
+	poetry run pre-commit autoupdate --repo https://github.com/pre-commit/pre-commit-hooks
+	poetry run pre-commit autoupdate --repo https://github.com/astral-sh/ruff-pre-commit
 
 #==============================================================================
 ##@ CI/CD Operations
 #==============================================================================
 
 cicd: _check-docker _check-act ## Run CI/CD pipeline (use job=<name> or workflow=<name>)
 	@echo -e  "$(BOLD)$(BLUE)Running CI/CD pipeline...$(RESET)"
-	@if [ -n "$(workflow)" ]; then \
+	@ACT_SECRETS=""; \
+	if [ -f .secrets ]; then \
+		ACT_SECRETS="--secret-file .secrets"; \
+	else \
+		echo -e "$(YELLOW)Warning: .secrets file not found. Create one from .secrets.example for GitHub Actions to work.$(RESET)"; \
+	fi; \
+	if [ -n "$(workflow)" ]; then \
 		echo -e "$(YELLOW)Running workflow: $(workflow)$(RESET)"; \
-		act -W "$(WORKFLOWS_DIR)/$(workflow).yml" --container-architecture $(ACT_ARCH) -P $(ACT_PLATFORM); \
+		act -W "$(WORKFLOWS_DIR)/$(workflow).yml" --container-architecture $(ACT_ARCH) -P $(ACT_PLATFORM) $$ACT_SECRETS; \
 	elif [ -n "$(job)" ]; then \
 		echo -e "$(YELLOW)Running job: $(job)$(RESET)"; \
-		act --job $(job) --container-architecture $(ACT_ARCH) -P $(ACT_PLATFORM); \
+		act --job $(job) --container-architecture $(ACT_ARCH) -P $(ACT_PLATFORM) $$ACT_SECRETS; \
 	else \
 		echo -e "$(YELLOW)Available jobs and workflows:$(RESET)"; \
 		act --list --container-architecture $(ACT_ARCH); \

docs/Developing-Stonks-Overwatch.md

@@ -142,6 +142,39 @@ These commands will check the code linting or do the best effort to properly for
 Make sure to execute `make pre-commit-install` to install the pre-commit hooks, so the code is automatically checked
 before committing.
 
+#### Pre-commit Hooks
+
+The project uses pre-commit hooks to maintain code quality. The hooks include:
+
+- Code formatting (Ruff)
+- Python linting (Ruff)
+- YAML validation
+- Markdown linting
+- Link checking (Lychee)
+- Poetry validation
+- Django system checks
+- Test execution
+
+**Installing hooks:**
+
+```shell
+make pre-commit-install
+```
+
+**Running hooks manually:**
+
+```shell
+make pre-commit-run
+```
+
+**Updating hook versions:**
+
+```shell
+make pre-commit-update
+```
+
+> **Note on Lychee**: The link checker (Lychee) uses a non-standard tag format (`lychee-vX.Y.Z`) which is excluded from automatic updates. The `make pre-commit-update` command only updates the `pre-commit-hooks` and `ruff-pre-commit` repositories to prevent reverting Lychee to a mutable `nightly` branch reference. If you need to update Lychee, manually edit `.pre-commit-config.yaml` and change the `rev` to the desired stable tag (e.g., `lychee-v0.22.0`).
+
 ### Test
 
 ```shell
@@ -202,7 +235,86 @@ As before, only the application for the current OS will be created and executed.
 make cicd
 ```
 
-Will execute the GitHub Actions locally. It's a good way of validating changes in the CI/CD code
+Will execute the GitHub Actions locally using [ACT](https://github.com/nektos/act). It's a good way of validating changes in the CI/CD code before pushing to GitHub.
+
+#### Setting up ACT for Local CI/CD Testing
+
+ACT requires a GitHub Personal Access Token to clone GitHub Actions (like `actions/setup-python`, `actions/cache`, etc.).
+
+**Initial Setup:**
+
+1. **Create a GitHub Personal Access Token:**
+   - Go to: [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new)
+   - Token name: "ACT Local Testing"
+   - Expiration: Your choice (90 days recommended)
+   - Select scopes: Check **"public_repo"** (for public repositories)
+   - Click "Generate token"
+   - Copy the token (you won't see it again!)
+
+2. **Create `.secrets` file:**
+
+   ```shell
+   cp .secrets.example .secrets
+   ```
+
+3. **Edit `.secrets` and add your token:**
+
+   ```bash
+   GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+   ```
+
+   Replace `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` with your actual token.
+
+4. **Test it:**
+
+   ```shell
+   make cicd job=lint
+   ```
+
+> **Security Note**: The `.secrets` file is already in `.gitignore` and will never be committed to the repository.
+
+**Running Specific Jobs:**
+
+```shell
+# Run the lint job
+make cicd job=lint
+
+# Run the test job
+make cicd job=test
+
+# List all available jobs
+make cicd
+```
+
+**Running Specific Workflows:**
+
+```shell
+# Run the entire CI/CD workflow
+make cicd workflow=cicd
+
+# Run the pre-commit autoupdate workflow
+make cicd workflow=precommit-autoupdate
+```
+
+**Troubleshooting ACT:**
+
+If you see authentication errors like `authentication required: Invalid username or token`, ensure:
+- Your `.secrets` file exists and contains a valid `GITHUB_TOKEN`
+- The token has the `public_repo` scope enabled
+- You've copied the token correctly (no extra spaces or newlines)
+
+**Note on Lychee Link Checking:**
+The link checking step (lychee) is automatically skipped when running with ACT due to architecture compatibility issues (ARM64 vs x86_64). The lychee check will still run in the actual GitHub Actions environment. You can verify links locally by running:
+
+```shell
+make markdown-links-check
+```
+
+Or through pre-commit hooks:
+
+```shell
+make pre-commit-run
+```
 
 ## Troubleshooting