Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .extensionignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Files not copied into a project by `specify extension add`
tests/
.github/
.gitignore
CHANGELOG.md
80 changes: 80 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
name: Release

# Push a tag like v1.1.0 to publish a release. The tag must match the version
# in extension.yml, and CHANGELOG.md needs a "## [1.1.0]" section.

on:
push:
tags: ["v*"]

permissions:
contents: write

jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Check version
id: version
run: |
TAG="${GITHUB_REF_NAME}"
VERSION="${TAG#v}"
MANIFEST_VERSION="$(grep -E '^[[:space:]]+version:' extension.yml | head -1 | sed -E 's/.*version:[[:space:]]*"?([^"]+)"?.*/\1/')"
if [[ "$VERSION" != "$MANIFEST_VERSION" ]]; then
echo "::error::Tag $TAG does not match extension.yml version $MANIFEST_VERSION"
exit 1
fi
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::Version must be X.Y.Z (got $VERSION)"
exit 1
fi
if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then
echo "::error::CHANGELOG.md has no section for $VERSION"
exit 1
fi
if ! grep -q "/download/v$VERSION/" README.md; then
echo "::error::README.md install command doesn't point to v$VERSION"
exit 1
fi
echo "version=$VERSION" >> "$GITHUB_OUTPUT"

- name: Run tests
run: bash tests/test-helpers.sh

- name: Build archive
run: |
mkdir -p dist
zip -r -X dist/spec-kit-gitlab.zip \
extension.yml README.md LICENSE CHANGELOG.md .extensionignore \
gitlab-config.template.yml commands scripts
(cd dist && sha256sum spec-kit-gitlab.zip > spec-kit-gitlab.zip.sha256)
cat dist/spec-kit-gitlab.zip.sha256

- name: Release notes
run: |
awk -v v="${{ steps.version.outputs.version }}" '
$0 ~ "^## \\[" v "\\]" { found = 1; next }
found && /^## \[/ { exit }
found { print }
' CHANGELOG.md > dist/notes.md
{
echo
echo "## Install"
echo
echo '```bash'
echo "specify extension add gitlab --from https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/spec-kit-gitlab.zip"
echo '```'
echo
echo "SHA-256: \`$(cut -d' ' -f1 dist/spec-kit-gitlab.zip.sha256)\`"
} >> dist/notes.md

- name: Create release
env:
GH_TOKEN: ${{ github.token }}
run: |
gh release create "$GITHUB_REF_NAME" \
dist/spec-kit-gitlab.zip dist/spec-kit-gitlab.zip.sha256 \
--title "$GITHUB_REF_NAME" \
--notes-file dist/notes.md
30 changes: 30 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Test

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
helpers:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
steps:
- uses: actions/checkout@v4
- name: Install jq (macOS)
if: runner.os == 'macOS'
run: command -v jq || brew install jq
- name: Run helper tests
run: bash tests/test-helpers.sh

shellcheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: ShellCheck
run: shellcheck --severity=warning -s bash scripts/bash/gitlab-helpers.sh tests/test-helpers.sh
48 changes: 48 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Changelog

All notable changes to this extension are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.1.0] - 2026-11-05

Brings the extension up to date with spec-kit 1.3 and the current glab CLI.

### Changed

- Requires spec-kit `>=0.12.17` and glab `>=1.50.0`; `jq` is now listed as a required tool.
- Command frontmatter uses the standard `scripts: {sh, ps}` keys with the `{SCRIPT}` placeholder. The old custom keys (`gitlab-helpers.sh: ...`) and `{SCRIPT:name}` placeholders made the registrar fail ("No runnable script variant") and were never substituted.
- The feature directory is resolved with `check-prerequisites --json --paths-only`, so commands no longer require `plan.md` and use the correct `.specify/scripts/bash/` path.
- Commands reference each other with `__SPECKIT_COMMAND_*__` tokens instead of hard-coded `/speckit.*` invocations, so they render correctly for skills-based agents. `/speckit.spec` (which doesn't exist) is replaced with the specify command.
- Task parsing follows the spec-kit `tasks.md` format: `[P]` is the parallel marker, `[US1]` the story, and `[X]` counts as done. A task inherits its priority from its story. Legacy `[P1]` markers still work.
- Story parsing follows the spec-kit `spec.md` format `### User Story 1 - Title (Priority: P1)`. The legacy `### US1: Title [P1]` format still works.
- Task IDs with four or more digits (`T1000`) are supported.
- The local override `gitlab-config.local.yml` (or `local-config.yml`) now overrides individual keys instead of replacing the whole configuration.
- The config template uses empty values instead of `${GITLAB_URL}` placeholders, since spec-kit copies it into the project on install and doesn't expand placeholders.

### Added

- Optional `after_implement` hook that offers to close completed tasks in GitLab.
- `mapping.task_issue_type` (`task` or `issue`) to choose the GitLab type of task issues.
- Helpers `parse_tasks`, `parse_stories`, `list_mapping_ids`, `set_task_checkbox`, `annotate_task_issue`, `glab_set_issue_type`, `glab_check_connection`, and `label_to_priority`.
- `--dry-run` for close-issues and sync, `--no-update` for status.
- Offline tests (`tests/test-helpers.sh`) and a CI workflow.
- `.extensionignore`, so tests and CI files aren't copied into projects.
- Release workflow: pushing a `vX.Y.Z` tag publishes a GitHub release with an installable `spec-kit-gitlab.zip` and its SHA-256, so the extension installs with a single `specify extension add ... --from <release URL>`.

### Fixed

- `glab issue create --type` doesn't exist; the task type is now set through the API after creation.
- `glab issue relation` doesn't exist; issues are linked with `--linked-issues` on creation or through the issue links API.
- `glab issue list --state all` doesn't exist and only returned the first 30 issues; issues are now listed through the API with pagination.
- `glab api` has no `--repo` flag; API calls use `--hostname` and the URL-encoded project path, so they work outside a clone of the GitLab project and with self-hosted instances.
- The mapping file was written as invalid YAML (`stories: {}` followed by entries).
- Sourcing the helper script no longer turns on `set -euo pipefail` in the caller's shell.
- YAML parsing works with BSD/macOS `sed` and ignores trailing comments.

## [1.0.0]

### Added

- Initial release: init, feature-to-issue, import-feature, stories-to-issues, tasks-to-issues, close-issues, sync, and status commands.
151 changes: 93 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,52 @@

GitLab integration for [spec-kit](https://github.com/github/spec-kit): create issues, sync, and post status updates via the `glab` CLI.

Supports self-hosted GitLab instances.
Supports gitlab.com and self-hosted GitLab instances.

## Requirements

- **spec-kit** >= 0.1.0
- **glab CLI** >= 1.0.0 ([GitLab CLI](https://gitlab.com/gitlab-org/cli))
- **spec-kit** >= 0.12.17 (tested against the 1.3 extension format)
- **glab CLI** >= 1.50.0 ([GitLab CLI](https://gitlab.com/gitlab-org/cli))
- **jq**
- **bash** (macOS, Linux, or Git Bash/WSL on Windows)

## Installation

In your spec-kit project:

```bash
specify extension add gitlab --from https://github.com/ohartwig/spec-kit-gitlab/releases/download/v1.1.0/spec-kit-gitlab.zip
```

Then run the setup command `speckit.gitlab.init` in your coding agent. Done.

On install, spec-kit copies the config template to `.specify/extensions/gitlab/gitlab-config.yml` and registers the commands for your coding agent. Each [release](https://github.com/ohartwig/spec-kit-gitlab/releases) lists its install command and the archive's SHA-256.

If `glab` and `jq` aren't installed yet:

```bash
# Install and authenticate the glab CLI
brew install glab
brew install glab jq # macOS; other systems: https://gitlab.com/gitlab-org/cli#installation
glab auth login --hostname gitlab.example.com
```

<details>
<summary>Other ways to install</summary>

```bash
# Latest development version (main branch)
specify extension add gitlab --from https://github.com/ohartwig/spec-kit-gitlab/archive/refs/heads/main.zip

# Install the extension (development mode)
cd /path/to/your/spec-kit-project
# From a local clone (development mode, picks up changes without reinstalling)
specify extension add --dev ~/spec-kit-gitlab/
```

## Configuration
To update, run the install command of the new release with `--force`. Your `gitlab-config.yml` and `gitlab-config.local.yml` are kept.

The easiest way is via the interactive setup:
</details>

```bash
/speckit.gitlab.init
```
## Configuration

This creates the configuration file at `.specify/extensions/gitlab/gitlab-config.yml`:
The easiest way is the interactive setup command (`speckit.gitlab.init`, see [Invoking the commands](#invoking-the-commands)). It writes `.specify/extensions/gitlab/gitlab-config.yml`:

```yaml
gitlab:
Expand All @@ -43,82 +61,90 @@ labels:
feature_label: "feature"

mapping:
priority_to_label: true # P1/P2/P3 β†’ priority::1/2/3
feature_to_milestone: true # Feature name as a GitLab milestone
priority_to_label: true # Story priority P1/P2/P3 β†’ priority::1/2/3
feature_to_milestone: true # Feature directory name as a GitLab milestone
feature_to_issue: true # Create the feature as a GitLab issue
link_tasks_to_stories: true # Link tasks to story issues
link_tasks_to_stories: true # Link task issues to story issues
task_issue_type: "task" # GitLab type for task issues: "task" or "issue"
```

Alternatively, via environment variables:
Configuration is resolved in this order (highest first):

```bash
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_PROJECT="group/project"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
```
1. Environment variables `GITLAB_URL` and `GITLAB_PROJECT`
2. Local overrides in `.specify/extensions/gitlab/gitlab-config.local.yml` (per key, not committed, kept on reinstall)
3. `.specify/extensions/gitlab/gitlab-config.yml`
4. Built-in defaults

Authentication is handled entirely by `glab` (`glab auth login`, or `GITLAB_TOKEN` with the `api` scope). Never put a token in the config file.

## Invoking the commands

The command names below are the extension's command IDs. How you type them depends on your coding agent, for example `/speckit.gitlab.init` for agents with slash commands, or `/speckit-gitlab-init` for agents that use skills (such as GitHub Copilot's skills layout). See spec-kit's [command invocation reference](https://github.com/github/spec-kit/blob/main/docs/integrations/cli.md#command-invocation).

## Commands

### `/speckit.gitlab.init`
### `speckit.gitlab.init`

Interactive setup of the GitLab configuration. Checks the `glab` installation, tests the connection, and writes the configuration file.
Interactive setup of the GitLab configuration. Checks `glab` and `jq`, suggests values from the git remote, tests the connection, and writes the configuration file.

### `/speckit.gitlab.feature-to-issue`
### `speckit.gitlab.feature-to-issue`

Creates a GitLab issue for the current feature and links existing story issues to it. Uses the feature directory name as the title and the context from `spec.md` as the description. Labels: `spec-kit`, `feature`.
Creates a GitLab issue for the current feature and links existing story issues to it. Uses the feature name from `spec.md` as the title and the overview section as the description. Labels: `spec-kit`, `feature`.

### `/speckit.gitlab.import-feature`
### `speckit.gitlab.import-feature`

Imports an existing GitLab issue as a feature. Argument: issue number (e.g. `232` or `#232`). Writes the mapping, optionally creates a `spec.md` from the issue description, and links existing stories.
Imports an existing GitLab issue as a feature. Argument: issue number (`232`, `#232`) or issue URL. Writes the mapping, optionally seeds `spec.md` from the issue description, and links existing stories.

### `/speckit.gitlab.stories-to-issues`
### `speckit.gitlab.stories-to-issues`

Creates GitLab issues for all user stories from `spec.md`. Expects the format `### US1: Title [P1]` and automatically assigns labels (`spec-kit`, `user-story`, `priority::X`). Automatically links new stories to the feature issue (if one exists).
Creates GitLab issues for all user stories in `spec.md`. Reads the spec-kit template format `### User Story 1 - Title (Priority: P1)` (the older `### US1: Title [P1]` still works) and sets the labels `spec-kit`, `user-story`, and `priority::N`. New stories are linked to the feature issue, if there is one.

### `/speckit.gitlab.tasks-to-issues`
### `speckit.gitlab.tasks-to-issues`

Creates GitLab issues (Type: Task) for all tasks from `tasks.md`. Expects the format `- [ ] T001 [P1] [US1] Description`. Automatically links tasks to their story issues.
Creates GitLab issues (type *Task* by default) for all tasks in `tasks.md`. Reads the spec-kit format `- [ ] T012 [P] [US1] Description`, where `[P]` marks a parallelizable task and `[US1]` the story. Tasks inherit the priority of their story and are linked to the story issue.

### `/speckit.gitlab.close-issues`
### `speckit.gitlab.close-issues`

Syncs the local completion status to GitLab. Tasks marked `[x]` in `tasks.md` are closed in GitLab; tasks reopened (`[ ]`) are reopened. Stories are automatically closed once all their tasks are complete.
Pushes the local completion status to GitLab. Tasks marked `[x]`/`[X]` in `tasks.md` are closed in GitLab, tasks reopened (`[ ]`) are reopened. Stories are closed once all their tasks are complete. Supports `--dry-run`.

### `/speckit.gitlab.sync`
### `speckit.gitlab.sync`

Syncs GitLab issue status into the local `tasks.md` files. Updates checkboxes based on issue status (open/closed). Shows the feature issue status (if one exists). Optional: imports new GitLab issues with `--import`.
Pulls the GitLab issue status into `tasks.md` (closed β†’ `[x]`, open β†’ `[ ]`) and shows the feature issue status. With `--import`, adds GitLab task issues that aren't in `tasks.md` yet. Supports `--dry-run`.

### `/speckit.gitlab.status`
### `speckit.gitlab.status`

Shows an overview of all GitLab issues with their current status (task ID, issue number, status, assignee) and updates `tasks.md`. Shows the feature issue status at the top of the overview. Includes progress statistics (open, closed, percent).
Shows an overview of all issues of the feature (task ID, issue number, status, assignee, story progress) and updates `tasks.md`. If local and GitLab status contradict each other, it asks which side wins. `--no-update` only shows the overview.

## Workflow

### Push workflow (Local β†’ GitLab)
### Push workflow (local β†’ GitLab)

```
1. /speckit.gitlab.init β†’ Set up the GitLab connection
2. /speckit.spec β†’ Create spec.md
3. /speckit.gitlab.feature-to-issue β†’ Create the feature as a GitLab issue
4. /speckit.tasks β†’ Generate tasks.md
5. /speckit.gitlab.stories-to-issues β†’ Stories as GitLab issues (linked to the feature)
6. /speckit.gitlab.tasks-to-issues β†’ Tasks as GitLab issues (linked to stories)
7. /speckit.gitlab.close-issues β†’ Close completed issues in GitLab
8. /speckit.gitlab.status β†’ Sync status
1. speckit.gitlab.init β†’ Set up the GitLab connection
2. speckit.specify β†’ Create spec.md
3. speckit.gitlab.feature-to-issue β†’ Feature as a GitLab issue
4. speckit.gitlab.stories-to-issues β†’ Stories as GitLab issues (linked to the feature)
5. speckit.plan, speckit.tasks β†’ Plan and generate tasks.md
6. speckit.gitlab.tasks-to-issues β†’ Tasks as GitLab issues (linked to stories)
7. speckit.implement β†’ Implement
8. speckit.gitlab.close-issues β†’ Close completed issues in GitLab
```

### Pull workflow (GitLab β†’ Local)
### Pull workflow (GitLab β†’ local)

```
1. /speckit.gitlab.import-feature 232 β†’ Import an existing issue as a feature
2. /speckit.spec β†’ Create/refine the specification
3. /speckit.tasks β†’ Generate tasks
4. /speckit.gitlab.stories-to-issues β†’ Stories as GitLab issues
5. /speckit.gitlab.tasks-to-issues β†’ Tasks as GitLab issues
1. speckit.specify <issue title> β†’ Start the feature in spec-kit
2. speckit.gitlab.import-feature 232 β†’ Link the feature to the existing issue
3. speckit.clarify β†’ Refine the specification
4. speckit.gitlab.stories-to-issues β†’ Stories as GitLab issues
5. speckit.plan, speckit.tasks β†’ Plan and generate tasks
6. speckit.gitlab.tasks-to-issues β†’ Tasks as GitLab issues
7. speckit.gitlab.sync β†’ Pull status changes made in GitLab
```

## Mapping file

The extension maintains a `.gitlab-mapping.yml` in the feature directory to ensure idempotency:
The extension keeps a `.gitlab-mapping.yml` in the feature directory, so commands can be run repeatedly without creating duplicates:

```yaml
feature: "#232 https://gitlab.example.com/group/project/-/issues/232"
Expand All @@ -128,13 +154,22 @@ tasks:
T001: "#42 https://gitlab.example.com/group/project/-/issues/42"
```

The `feature:` field is set by `/speckit.gitlab.feature-to-issue` (push) or `/speckit.gitlab.import-feature` (pull). Stories are automatically linked to the feature issue.
Task lines in `tasks.md` also get a `<!-- gitlab:#42 -->` comment. The `feature:` entry is set by `speckit.gitlab.feature-to-issue` (push) or `speckit.gitlab.import-feature` (pull).

## Hooks

- **after_tasks**: after task generation, you're asked whether to create the tasks as GitLab issues.
- **after_implement**: after implementation, you're asked whether to close completed tasks in GitLab.

This lets commands be run multiple times without creating duplicates.
Both hooks are optional and can be turned off in `.specify/extensions.yml`.

## Hook
## Development

```bash
bash tests/test-helpers.sh
```

After `/speckit.tasks`, you're automatically asked whether tasks should be created as GitLab issues.
The tests cover config loading, `tasks.md`/`spec.md` parsing, and the mapping file. They run offline. `tests/`, `.github/`, and `CHANGELOG.md` are excluded from installation via `.extensionignore`.

## License

Expand Down
Loading
Loading