subculture-collective/mandalay
1
0
Fork 0
Code Issues 13 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Add CI/CD documentation to README

Browse Source 
Co-authored-by: PatrickFanella <61631520+PatrickFanella@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-05 16:00:54 +00:00
parent 476dc6a358
commit 5b6be15c5c
1 changed files with 112 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

240
README.md
View File

@@ -1,153 +1,137 @@
actionlint
==========
[![CI Badge][]][CI]
[![API Document][api-badge]][apidoc]
# Mandalay - Vegas Shooting Map Data
[actionlint][repo] is a static checker for GitHub Actions workflow files. [Try it online!][playground]
Go backend for extracting and managing KML geographic data from the Vegas Shooting Map in a PostGIS-enabled PostgreSQL database.
Features:
## Architecture
- **Syntax check for workflow files** to check unexpected or missing keys following [workflow syntax][syntax-doc]
- **Strong type check for `${{ }}` expressions** to catch several semantic errors like access to not existing property,
type mismatches, ...
- **Actions usage check** to check that inputs at `with:` and outputs in `steps.{id}.outputs` are correct
- **Reusable workflow check** to check inputs/outputs/secrets of reusable workflows and workflow calls
- **[shellcheck][] and [pyflakes][] integrations** for scripts at `run:`
- **Security checks**; [script injection][script-injection-doc] by untrusted inputs, hard-coded credentials
- **Other several useful checks**; [glob syntax][filter-pattern-doc] validation, dependencies check for `needs:`,
runner label validation, cron syntax validation, ...
- **Backend**: Go with pgx for PostgreSQL connectivity
- **Database**: PostgreSQL 16 with PostGIS 3.4 (Docker)
- **Data Source**: KMZ/KML file containing 545 placemarks (420 points, 50 lines, 75 polygons)
See [the full list](docs/checks.md) of checks done by actionlint.
<img src="https://github.com/rhysd/ss/blob/master/actionlint/main.gif?raw=true" alt="actionlint reports 7 errors" width="806" height="492"/>
**Example of broken workflow:**
```yaml
on:
push:
branch: main
tags:
- 'v\d+'
jobs:
test:
strategy:
matrix:
os: [macos-latest, linux-latest]
runs-on: ${{ matrix.os }}
steps:
- run: echo "Checking commit '${{ github.event.head_commit.message }}'"
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node_version: 16.x
- uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ matrix.platform }}-node-${{ hashFiles('**/package-lock.json') }}
if: ${{ github.repository.permissions.admin == true }}
- run: npm install && npm test
```
**actionlint reports 7 errors:**
## Project Structure
```
test.yaml:3:5: unexpected key "branch" for "push" section. expected one of "branches", "branches-ignore", "paths", "paths-ignore", "tags", "tags-ignore", "types", "workflows" [syntax-check]
|
3 | branch: main
| ^~~~~~~
test.yaml:5:11: character '\' is invalid for branch and tag names. only special characters [, ?, +, *, \ ! can be escaped with \. see `man git-check-ref-format` for more details. note that regular expression is unavailable. note: filter pattern syntax is explained at https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet [glob]
|
5 | - 'v\d+'
| ^~~~
test.yaml:10:28: label "linux-latest" is unknown. available labels are "windows-latest", "windows-2022", "windows-2019", "windows-2016", "ubuntu-latest", "ubuntu-22.04", "ubuntu-20.04", "ubuntu-18.04", "macos-latest", "macos-12", "macos-12.0", "macos-11", "macos-11.0", "macos-10.15", "self-hosted", "x64", "arm", "arm64", "linux", "macos", "windows". if it is a custom label for self-hosted runner, set list of labels in actionlint.yaml config file [runner-label]
|
10 | os: [macos-latest, linux-latest]
| ^~~~~~~~~~~~~
test.yaml:13:41: "github.event.head_commit.message" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions for more details [expression]
|
13 | - run: echo "Checking commit '${{ github.event.head_commit.message }}'"
| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
test.yaml:17:11: input "node_version" is not defined in action "actions/setup-node@v3". available inputs are "always-auth", "architecture", "cache", "cache-dependency-path", "check-latest", "node-version", "node-version-file", "registry-url", "scope", "token" [action]
|
17 | node_version: 16.x
| ^~~~~~~~~~~~~
test.yaml:21:20: property "platform" is not defined in object type {os: string} [expression]
|
21 | key: ${{ matrix.platform }}-node-${{ hashFiles('**/package-lock.json') }}
| ^~~~~~~~~~~~~~~
test.yaml:22:17: receiver of object dereference "permissions" must be type of object but got "string" [expression]
|
22 | if: ${{ github.repository.permissions.admin == true }}
| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mandalay/
├── cmd/
│ └── import/ # KML import CLI tool
├── data/
│ └── raw/ # Extracted KML and assets
├── docker-compose.yml # PostgreSQL/PostGIS container
├── .env # Database connection config
└── go.mod
```
## Why?
## Database Schema
- **Running a workflow is time consuming.** You need to push the changes and wait until the workflow runs on GitHub even if
it contains some trivial mistakes. [act][] is useful to debug the workflow locally. But it is not suitable for CI and still
time consuming when your workflow gets larger.
- **Checks of workflow files by GitHub are very loose.** It reports no error even if unexpected keys are in mappings
(meant that some typos in keys). And also it reports no error when accessing to property which is actually not existing.
For example `matrix.foo` when no `foo` is defined in `matrix:` section, it is evaluated to `null` and causes no error.
- **Some mistakes silently break a workflow.** Most common case I saw is specifying missing property to cache key. In the
case cache silently does not work properly but a workflow itself runs without error. So you might not notice the mistake
forever.
### Tables
## Quick start
**styles** - KML style definitions
- `id` (PK) - Style identifier
- `icon_href`, `icon_scale`, `label_scale` - Icon styling
- `raw_xml` - Original XML
Install `actionlint` command by downloading [the released binary][releases] or by Homebrew or by `go install`. See
[the installation document](docs/install.md) for more details like how to manage the command with several package managers
or run via Docker container.
**placemarks** - Geographic features
- `id` (PK, serial)
- `name`, `description` - Feature metadata
- `style_id` (FK → styles)
- `folder_path` (text[]) - Hierarchical location
- `geometry_type` - Point/LineString/Polygon
- `geom` (geometry SRID 4326) - PostGIS geometry
- `coordinates_raw` - Original coordinate text
- `gx_media_links` (text[]) - YouTube/media URLs
- `created_at` - Timestamp
```sh
go install github.com/rhysd/actionlint/cmd/actionlint@latest
**placemark_data** - Extended key-value attributes
- `placemark_id` (FK → placemarks)
- `key`, `value`
### Indexes
- GIST index on `geom` for spatial queries
- GIN index on `folder_path` for hierarchy queries
## Quick Start
### 1. Start PostgreSQL
```bash
docker-compose up -d
```
Basically all you need to do is run the `actionlint` command in your repository. actionlint automatically detects workflows and
checks errors. actionlint focuses on finding out mistakes. It tries to catch errors as much as possible and make false positives
as minimal as possible.
Container runs at `localhost:5432` with credentials:
- User: `mandalay`
- Password: `mandalay`
- Database: `vegasmap`
```sh
actionlint
### 2. Import KML Data
```bash
# Dry run (parse only, no database writes)
go run cmd/import/main.go --dry-run
# Import with existing data truncation
go run cmd/import/main.go --truncate
# Limit import for testing
go run cmd/import/main.go --limit 50
```
Another option to try actionlint is [the online playground][playground]. Your browser can run actionlint through WebAssembly.
### 3. Query the Data
See [the usage document](docs/usage.md) for more details.
```bash
# Connect to database
PGPASSWORD=mandalay psql -h localhost -U mandalay -d vegasmap
## Documents
# Sample queries
SELECT geometry_type, COUNT(*) FROM placemarks GROUP BY geometry_type;
SELECT name, ST_AsText(geom) FROM placemarks WHERE geometry_type = 'Point' LIMIT 5;
```
- [Checks](docs/checks.md): Full list of all checks done by actionlint with example inputs, outputs, and playground links.
- [Installation](docs/install.md): Installation instructions. Prebuilt binaries, Homebrew package, a Docker image, building from
source, a download script (for CI) are available.
- [Usage](docs/usage.md): How to use `actionlint` command locally or on GitHub Actions, the online playground, an official Docker
image, and integrations with reviewdog, Problem Matchers, super-linter, pre-commit, VS Code.
- [Configuration](docs/config.md): How to configure actionlint behavior. Currently only labels of self-hosted runners can be
configured.
- [Go API](docs/api.md): How to use actionlint as Go library.
- [References](docs/reference.md): Links to resources.
## Current Status
## Bug reporting
✅ 545 placemarks imported
✅ 44 styles loaded
✅ PostGIS spatial indexes created
✅ Docker containerized database
✅ CI/CD pipeline with automated checks
When you see some bugs or false positives, it is helpful to [file a new issue][issue-form] with a minimal example
of input. Giving me some feedbacks like feature requests or ideas of additional checks is also welcome.
## CI/CD
## License
The project includes a GitHub Actions CI workflow that runs on pushes and pull requests to the main branch:
actionlint is distributed under [the MIT license](./LICENSE.txt).
**Frontend Checks:**
- **Lint**: ESLint validation of React/TypeScript code
- **Build**: TypeScript compilation and Vite production build
- **Test**: Vitest unit and integration tests
[CI Badge]: https://github.com/rhysd/actionlint/workflows/CI/badge.svg?branch=main&event=push
[CI]: https://github.com/rhysd/actionlint/actions?query=workflow%3ACI+branch%3Amain
[api-badge]: https://pkg.go.dev/badge/github.com/rhysd/actionlint.svg
[apidoc]: https://pkg.go.dev/github.com/rhysd/actionlint
[repo]: https://github.com/rhysd/actionlint
[playground]: https://rhysd.github.io/actionlint/
[shellcheck]: https://github.com/koalaman/shellcheck
[pyflakes]: https://github.com/PyCQA/pyflakes
[act]: https://github.com/nektos/act
[syntax-doc]: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
[filter-pattern-doc]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
[script-injection-doc]: https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#understanding-the-risk-of-script-injections
[issue-form]: https://github.com/rhysd/actionlint/issues/new
[releases]: https://github.com/rhysd/actionlint/releases
**Backend Checks:**
- **Go Vet**: Static analysis of Go code
- **Go Test**: Run all Go test suites
All jobs run in parallel with dependency caching (npm and Go modules) for optimal performance.
## Next Steps
- Build REST API for querying placemarks
- Add spatial query endpoints (bbox, radius search)
- Implement frontend map visualization
- Add data update/CRUD operations
## Environment
Copy `.env` and adjust if needed:
```
DATABASE_URL=postgresql://mandalay:mandalay@localhost:5432/vegasmap?sslmode=disable
```
## Dependencies
- Go 1.24+
- Docker & Docker Compose
- PostgreSQL client (optional, for psql)
```bash
go get github.com/jackc/pgx/v5
go get github.com/jackc/pgx/v5/pgxpool
go get github.com/joho/godotenv
```