chore: add CI workflow, release workflow, and project documentation

- Add CI workflow with actionlint and action.yml validation
- Add release workflow for retagging major versions
- Include CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, and SECURITY.md
- Add README with installation examples and configuration options
- Include example branch protection settings and workflow configurations

Signed-off-by: igorjs <oss@mail.igorjs.io>

Author: igorjs

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: actionlint
+        uses: rhysd/actionlint@v1
+      - name: Validate action.yml
+        run: |
+          test -f action.yml || (echo "action.yml missing" && exit 1)
+          grep -q "runs:" action.yml

.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  retag-major:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Move major tag (v1 → latest)
+        env:
+          TAG_REF: ${{ github.ref_name }} # e.g. v1.3.0
+        run: |
+          set -euo pipefail
+          git config user.name  "release[bot]"
+          git config user.email "release[bot]@users.noreply.github.com"
+          [[ "$TAG_REF" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Not a semver tag"; exit 1; }
+          MAJOR="${TAG_REF%%.*}"            # v1
+          git tag -f "$MAJOR" "$TAG_REF"
+          git push -f origin "$MAJOR"

CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment‑free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio‑economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation【426605577719396†L4-L13】. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment include demonstrating empathy and kindness toward other people, being respectful of differing opinions, viewpoints, and experiences, giving and gracefully accepting constructive feedback, apologising to those affected by mistakes and learning from the experience, and focusing on what is best for the overall community【771408749191128†L16-L25】.
+
+Examples of unacceptable behaviour include the use of sexualised language or imagery, trolling, insulting or derogatory comments, personal or political attacks, public or private harassment, publishing others’ private information, and other conduct which could reasonably be considered inappropriate in a professional setting【771408749191128†L27-L37】.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behaviour. They have the right to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate【771408749191128†L39-L49】.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event【771408749191128†L51-L58】.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the maintainers at **[INSERT CONTACT METHOD]**. All complaints will be reviewed and investigated promptly and fairly【771408749191128†L59-L66】. The maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+Enforcement follows these community impact guidelines:
+
+1. **Correction** – A private, written warning and request for apology for a first violation【771408749191128†L74-L82】.
+2. **Warning** – A warning with consequences for continued behaviour and a specified period of no interaction with those enforcing the Code【771408749191128†L83-L93】.
+3. **Temporary Ban** – A temporary ban from public interaction for serious violations【771408749191128†L95-L103】.
+4. **Permanent Ban** – A permanent ban from the community for sustained or extreme violations【771408749191128†L106-L113】.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1【771408749191128†L116-L119】, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thank you for considering contributing to this project! The merge queue action is maintained by volunteers, and contributions of all kinds are welcome.
+
+## Getting Started
+
+1. **Fork** this repository and create a branch for your feature or bug fix. Use a descriptive branch name (for example, `feature/fastlane-optimisation`).
+2. **Discuss** your proposed change by opening an issue. This helps avoid duplication and ensures your work aligns with project goals.
+3. **Develop** your change. Write clear commit messages and add tests where appropriate.
+4. **Submit a pull request (PR).** Describe your changes and reference the issue you’re addressing. PRs will be queued and merged by the action once approved.
+5. **Keep your PR up to date.** If your branch falls far behind the base, the action can auto‑update it if configured; otherwise please rebase or merge from the base branch.
+
+## Code of Conduct
+
+This project and all contributors are expected to abide by our Code of Conduct. It outlines behaviours that contribute to a positive environment and those that are unacceptable【426605577719396†L16-L39】. Instances of abusive or harassing behaviour may be reported to the maintainers.
+
+## Support
+
+For general questions or suggestions that are not feature requests or bug reports, you can open a discussion in the repository or contact the maintainers directly.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 igorjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software【16404071374199†L4-L16】.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE【16404071374199†L14-L19】.

README.md

@@ -0,0 +1,102 @@
+# Merge Queue GitHub Action
+
+This repository provides a GitHub composite action that implements a **merge queue** with an optional hot‑fix fastlane. The queue is FIFO (first‑in, first‑out) and works on GitHub Free and private repositories. Merges are staged on a temporary branch before reaching your protected branch, ensuring that only tested code lands on `master`/`main`.
+
+## Features
+
+* **FIFO merge queue** – Pull requests are merged in the order they were approved.
+* **Hot‑fix fastlane** – Pull requests whose branch name or title matches a configurable regex (for example `hotfix/`) bypass the queue.
+* **Auto‑update of stale branches** – Optionally update PR branches that have fallen behind your base by a specified number of commits.
+* **Shadow vs. live mode** – Shadow mode tests your configuration without merging; live mode performs actual merges.
+* **No additional services required** – Uses the built‑in `GITHUB_TOKEN` only; no enterprise features or external CI are required.
+
+## Installation
+
+Add the action to your workflow by referencing the tag in your repository. Make sure your repository’s **Settings → Branch protection** requires the custom status set in `status_context` (default `merge‑queue`) and disables **“Require branches to be up to date with base”**.
+
+### Example: shadow mode
+
+```yaml
+name: Merge Queue (shadow)
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review, synchronize, converted_to_draft, review_requested]
+  schedule:
+    - cron: "*/5 * * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+  statuses: write
+
+concurrency:
+  group: merge-queue
+  cancel-in-progress: true
+
+jobs:
+  queue:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: igorjs/gh-actions-merge-queue@v1
+        with:
+          base_branch: main
+          mode: shadow
+          merge_method: merge
+          status_context: merge-queue
+          behind_max_commits: "100"
+          fastlane_matchers: "^(hotfix|critical|security)/,\\bhotfix\\b,^hotfix:"
+```
+
+### Example: live mode
+
+To enable real merges, flip `mode` to `live` and adjust your branch protection accordingly.
+
+```yaml
+      - uses: igorjs/gh-actions-merge-queue@v1
+        with:
+          base_branch: main
+          mode: live
+          merge_method: merge
+          status_context: merge-queue
+          behind_max_commits: "100"
+```
+
+## Inputs
+
+This action exposes a number of inputs to customise behaviour:
+
+* **token** – Optional, defaults to `GITHUB_TOKEN`.
+* **base_branch** – Base branch to merge into (default `master`).
+* **queue_branch** – Temporary branch used to stage the merge (default `merge‑queue/staging`).
+* **fastlane_branch** – Temporary branch for fastlane merges (default `merge‑queue/fastlane`).
+* **state_branch** – Branch that stores the FIFO queue file (default `merge‑queue/state`).
+* **queue_file** – Path to the queue JSON file inside the state branch (default `.github/merge‑queue‑queue.json`).
+* **status_context** – Commit status context; must be required in branch protection (default `merge‑queue`).
+* **mode** – `shadow` or `live` (default `shadow`).
+* **fastlane_matchers** – Comma‑separated regex patterns used to detect fastlane PRs.
+* **behind_max_commits** – Update PR branches if behind more than this number of commits (0 disables).
+* **merge_method** – `merge` (preserves the tested tree) or `squash`.
+* **clean_queue** – Whether to delete the temporary queue branches (default `true`).
+
+## Branch protection
+
+1. Protect your base branch (`master` or `main`).
+2. Require pull request reviews as you normally do.
+3. Add the status context specified in your workflow (default `merge‑queue`) as the only required status check.
+4. Turn **off** “Require branches to be up to date before merging.”
+5. Allow **merge commits** (recommended) or configure your merge method to squash.
+
+For more information on branch protection and security policies, see the GitHub documentation【162389469722289†L471-L485】.
+
+## License
+
+This project is licensed under the MIT License. The MIT License allows free use, modification, and distribution of the software, provided that the copyright notice and license text appear in all copies and substantial portions of the software【16404071374199†L4-L16】.
+
+## Code of Conduct
+
+Participation in this project is governed by a Code of Conduct that aims to create a welcoming and inclusive environment. The code is adapted from the Contributor Covenant v2.1 and outlines behaviours that foster a positive community and those that are unacceptable【426605577719396†L4-L27】. Please review it in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+
+## Security
+
+To report a security vulnerability, please see [`SECURITY.md`](SECURITY.md) for instructions on responsible disclosure.

SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+Only the **v1** series of the merge queue action is currently supported. When a new major version is released, support for previous major versions will end one year after release.
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability, please report it responsibly. You can either:
+
+* Email the maintainers at **oss@mail.igorjs.io**, or
+* Use GitHub’s **Report a vulnerability** feature to open a private security advisory.
+
+Please do not disclose security issues publicly until we have had a chance to review and fix them. We commit to respond within three business days and will work with you to coordinate disclosure and a fix. GitHub recommends linking to your security policy from your README【162389469722289†L471-L485】; doing so helps reporters find the correct procedure quickly.
+
+Thank you for helping to keep this project secure.