Flutter Package CI/CD Pipeline
Reusable pipeline pattern distilled from bloc, riverpod, Very Good Workflows, and flutter/packages, validated on production packages.
When to use
- New Flutter/Dart library (pub package) needs GitHub Actions
- Existing package CI needs audit, DRY refactor, or release automation
- User asks for pub.dev publish automation, Dependabot, or package quality gates
Quick start (new project)
- Profile the project — fill project-profile.md
- Copy scaffold — create
.github/actions/ + .github/workflows/ per profile toggles
- Customize placeholders — package name, repo, paths, optional jobs
- Validate locally —
dart format, flutter analyze, flutter test, flutter pub publish --dry-run, pana .
- Configure pub.dev OIDC — one-time admin setup (see reference.md)
- Enable Dependabot —
.github/dependabot.yml with project's pub workspaces
Architecture
Pull Request ─┬─ semantic-pr.yml (PR title convention)
├─ pr-tests.yml (multi-OS lint + test + dry-run)
├─ release-gate.yml (main-target PR: version/changelog/pana)
├─ check-generation.yml (optional: codegen drift)
└─ project-specific.yml (benchmarks, migration, docs)
Push main ────┬─ ci-main.yml (lint → test → publish dry-run)
└─ check-generation.yml
Push tag v* ──┬─ release-tags.yml
│ ├─ release-gate (validate)
│ ├─ publish (OIDC → pub.dev)
│ └─ github-release (optional CLI artifacts)
Schedule ─────┬─ nightly.yml
└─ dependabot.yml (weekly PRs)
Composite actions (DRY core)
Always prefer composite actions over duplicated workflow steps.
| Action |
Purpose |
setup-flutter |
Flutter SDK + pub get for root and optional workspaces |
package-hygiene |
README, LICENSE/NOTICE, license_checker, changelog-on-bump |
flutter-package-checks |
dart format, flutter analyze, flutter test (+ random seed) |
pana-score |
pub.dev quality gate (default min 130/160) |
coverage-report |
lcov summary, JUnit from machine report, artifacts |
Scaffold copies: reference.md
Workflow inventory
| Workflow |
Trigger |
Required? |
Notes |
ci-main.yml |
push main |
Yes |
paths-ignore for docs-only changes |
pr-tests.yml |
all PRs |
Yes |
OS matrix: ubuntu, macos, windows |
semantic-pr.yml |
PR events |
Recommended |
Conventional PR titles |
release-gate.yml |
PR → main |
Yes for publishable packages |
Strict changelog + smoke checks |
release-tags.yml |
tag v*.*.* |
Yes if publishing |
3 jobs: validate → publish → GH release |
check-generation.yml |
path-filtered |
If codegen committed |
generate && git diff --exit-code |
dependabot.yml |
weekly |
Recommended |
pub + github-actions |
nightly.yml |
cron |
Optional |
Full suite + benchmarks |
github-pages.yml |
push/PR |
Optional |
MkDocs or static docs |
Project adaptation checklist
Before generating files, determine:
Project profile:
- [ ] Package name and README usage grep pattern
- [ ] Default branch (main/master)
- [ ] Workspaces: example/, tool/*, packages/* (list paths)
- [ ] Has committed generated code? → check-generation.yml
- [ ] Has CLI binaries for GitHub Release? → release artifact step
- [ ] Has custom smoke tests? → release-gate generator step
- [ ] License checker config path (or disable)
- [ ] Min pana score (run `pana .` first)
- [ ] Docs site (MkDocs) → github-pages.yml
- [ ] Monorepo? → use melos/paths-filter instead of single-package actions
Full template: project-profile.md
Adaptation rules
Package name in hygiene checks
Replace README usage awk pattern with project identifiers:
# Example for package "my_package":
$0 ~ /(my_package|MyPackage)/
setup-flutter workspaces
Add install_<workspace> inputs for each extra pubspec.yaml (example, tool apps). Remove unused inputs in consuming workflows.
Multi-OS PR matrix
Run expensive checks (lychee, dart doc, pana) on ubuntu-latest only. Format/analyze on all OSes to catch path issues.
Release tag pattern
Must match pub.dev OIDC config:
- Git tag:
v0.1.0
- pubspec:
version: 0.1.0
- pub.dev tag pattern:
v{{version}}
OIDC publish constraints
- Publish job only on tag push (not
workflow_dispatch, not branch push)
- Job needs
permissions: id-token: write
- Use official
dart-lang/setup-dart/.github/workflows/publish.yml@v1
Dependabot pub directories
List every directory with its own pubspec.yaml. Root library packages typically omit pubspec.lock; Dependabot still works on pubspec.yaml.
Optional: approval gate before publish
Add environment: pub.dev to publish job and configure matching environment on pub.dev admin + GitHub repo settings.
Implementation workflow for the agent
When user asks to set up or port this pipeline:
- Read target project:
pubspec.yaml, example/, tool/, existing .github/, CHANGELOG.md, .pubignore
- Fill project profile (ask user for repo owner/name if unclear)
- Create composite actions first (stable foundation)
- Create workflows from smallest to largest:
semantic-pr → ci-main → pr-tests → release-gate → release-tags → dependabot
- Add optional workflows only if profile flags them
- Run local gates:
dart analyze, flutter test, pana ., flutter pub publish --dry-run
- Document pub.dev OIDC setup in
CONTRIBUTING.md (brief section)
Patterns from famous packages
| Source |
Pattern adopted |
| bloc |
Composite actions, semantic PR, pana gate, test randomization |
| riverpod |
paths-ignore for markdown, separate codegen drift workflow |
| Very Good Workflows |
Reusable job structure, coverage artifacts |
| flutter/packages |
OIDC publish, Dependabot for pub + actions |
| dart.dev |
dart-lang/setup-dart publish workflow, no long-lived secrets |
Anti-patterns
- Do not put
dart pub publish in a branch-triggered workflow (OIDC fails)
- Do not duplicate 50-line hygiene blocks across workflows — use composites
- Do not require
pubspec.lock in library root packages
- Do not ship
doc/api/ to pub.dev — exclude via .pubignore, generate in CI before dry-run
- Do not use
workflow_dispatch for production publish
Install
# This skill only
curl -fsSL https://raw.githubusercontent.com/Melsaeed276/cursor-skills/main/skills/flutter-package-ci-pipeline/install.sh | bash
# Or via root installer
curl -fsSL https://raw.githubusercontent.com/Melsaeed276/cursor-skills/main/scripts/install.sh | bash -s -- flutter-package-ci-pipeline
Then invoke: "Use the flutter-package-ci-pipeline skill to set up CI for this project."
Additional resources
1---2name: flutter-package-ci-pipeline3description: >-4 Design, scaffold, audit, and adapt GitHub Actions CI/CD for Flutter/Dart pub5 packages — composite actions, PR/main/release workflows, OIDC pub publish,6 Dependabot, semantic PRs, codegen drift checks, pana gates. Use when setting up7 or improving package pipelines, GitHub Actions, release automation, or8 copying CI patterns to a new Flutter/Dart library project.9metadata:10 source: https://skillmd.com/skills/melsaeed276/flutter-package-ci-pipeline11---1213# Flutter Package CI/CD Pipeline1415Reusable pipeline pattern distilled from **bloc**, **riverpod**, **Very Good Workflows**, and **flutter/packages**, validated on production packages.1617## When to use1819- New Flutter/Dart **library** (pub package) needs GitHub Actions20- Existing package CI needs audit, DRY refactor, or release automation21- User asks for pub.dev publish automation, Dependabot, or package quality gates2223## Quick start (new project)24251. **Profile the project** — fill [project-profile.md](project-profile.md)262. **Copy scaffold** — create `.github/actions/` + `.github/workflows/` per profile toggles273. **Customize placeholders** — package name, repo, paths, optional jobs284. **Validate locally** — `dart format`, `flutter analyze`, `flutter test`, `flutter pub publish --dry-run`, `pana .`295. **Configure pub.dev OIDC** — one-time admin setup (see [reference.md](reference.md#pubdev-oidc-setup))306. **Enable Dependabot** — `.github/dependabot.yml` with project's pub workspaces3132## Architecture3334```35Pull Request ─┬─ semantic-pr.yml (PR title convention)36 ├─ pr-tests.yml (multi-OS lint + test + dry-run)37 ├─ release-gate.yml (main-target PR: version/changelog/pana)38 ├─ check-generation.yml (optional: codegen drift)39 └─ project-specific.yml (benchmarks, migration, docs)4041Push main ────┬─ ci-main.yml (lint → test → publish dry-run)42 └─ check-generation.yml4344Push tag v* ──┬─ release-tags.yml45 │ ├─ release-gate (validate)46 │ ├─ publish (OIDC → pub.dev)47 │ └─ github-release (optional CLI artifacts)4849Schedule ─────┬─ nightly.yml50 └─ dependabot.yml (weekly PRs)51```5253## Composite actions (DRY core)5455Always prefer composite actions over duplicated workflow steps.5657| Action | Purpose |58|--------|---------|59| `setup-flutter` | Flutter SDK + `pub get` for root and optional workspaces |60| `package-hygiene` | README, LICENSE/NOTICE, license_checker, changelog-on-bump |61| `flutter-package-checks` | `dart format`, `flutter analyze`, `flutter test` (+ random seed) |62| `pana-score` | pub.dev quality gate (default min 130/160) |63| `coverage-report` | lcov summary, JUnit from machine report, artifacts |6465Scaffold copies: [reference.md](reference.md#composite-action-templates)6667## Workflow inventory6869| Workflow | Trigger | Required? | Notes |70|----------|---------|-----------|-------|71| `ci-main.yml` | push `main` | Yes | `paths-ignore` for docs-only changes |72| `pr-tests.yml` | all PRs | Yes | OS matrix: ubuntu, macos, windows |73| `semantic-pr.yml` | PR events | Recommended | Conventional PR titles |74| `release-gate.yml` | PR → `main` | Yes for publishable packages | Strict changelog + smoke checks |75| `release-tags.yml` | tag `v*.*.*` | Yes if publishing | 3 jobs: validate → publish → GH release |76| `check-generation.yml` | path-filtered | If codegen committed | `generate && git diff --exit-code` |77| `dependabot.yml` | weekly | Recommended | pub + github-actions |78| `nightly.yml` | cron | Optional | Full suite + benchmarks |79| `github-pages.yml` | push/PR | Optional | MkDocs or static docs |8081## Project adaptation checklist8283Before generating files, determine:8485```86Project profile:87- [ ] Package name and README usage grep pattern88- [ ] Default branch (main/master)89- [ ] Workspaces: example/, tool/*, packages/* (list paths)90- [ ] Has committed generated code? → check-generation.yml91- [ ] Has CLI binaries for GitHub Release? → release artifact step92- [ ] Has custom smoke tests? → release-gate generator step93- [ ] License checker config path (or disable)94- [ ] Min pana score (run `pana .` first)95- [ ] Docs site (MkDocs) → github-pages.yml96- [ ] Monorepo? → use melos/paths-filter instead of single-package actions97```9899Full template: [project-profile.md](project-profile.md)100101## Adaptation rules102103### Package name in hygiene checks104105Replace README usage awk pattern with project identifiers:106107```bash108# Example for package "my_package":109$0 ~ /(my_package|MyPackage)/110```111112### setup-flutter workspaces113114Add `install_<workspace>` inputs for each extra `pubspec.yaml` (example, tool apps). Remove unused inputs in consuming workflows.115116### Multi-OS PR matrix117118Run expensive checks (lychee, `dart doc`, pana) on `ubuntu-latest` only. Format/analyze on all OSes to catch path issues.119120### Release tag pattern121122Must match pub.dev OIDC config:123124- Git tag: `v0.1.0`125- pubspec: `version: 0.1.0`126- pub.dev tag pattern: `v{{version}}`127128### OIDC publish constraints129130- Publish job **only** on tag push (not `workflow_dispatch`, not branch push)131- Job needs `permissions: id-token: write`132- Use official `dart-lang/setup-dart/.github/workflows/publish.yml@v1`133134### Dependabot pub directories135136List every directory with its own `pubspec.yaml`. Root library packages typically **omit** `pubspec.lock`; Dependabot still works on `pubspec.yaml`.137138### Optional: approval gate before publish139140Add `environment: pub.dev` to publish job and configure matching environment on pub.dev admin + GitHub repo settings.141142## Implementation workflow for the agent143144When user asks to set up or port this pipeline:1451461. Read target project: `pubspec.yaml`, `example/`, `tool/`, existing `.github/`, `CHANGELOG.md`, `.pubignore`1472. Fill project profile (ask user for repo owner/name if unclear)1483. Create composite actions first (stable foundation)1494. Create workflows from smallest to largest: `semantic-pr` → `ci-main` → `pr-tests` → `release-gate` → `release-tags` → `dependabot`1505. Add optional workflows only if profile flags them1516. Run local gates: `dart analyze`, `flutter test`, `pana .`, `flutter pub publish --dry-run`1527. Document pub.dev OIDC setup in `CONTRIBUTING.md` (brief section)153154## Patterns from famous packages155156| Source | Pattern adopted |157|--------|-----------------|158| bloc | Composite actions, semantic PR, pana gate, test randomization |159| riverpod | `paths-ignore` for markdown, separate codegen drift workflow |160| Very Good Workflows | Reusable job structure, coverage artifacts |161| flutter/packages | OIDC publish, Dependabot for pub + actions |162| dart.dev | `dart-lang/setup-dart` publish workflow, no long-lived secrets |163164## Anti-patterns165166- Do **not** put `dart pub publish` in a branch-triggered workflow (OIDC fails)167- Do **not** duplicate 50-line hygiene blocks across workflows — use composites168- Do **not** require `pubspec.lock` in library root packages169- Do **not** ship `doc/api/` to pub.dev — exclude via `.pubignore`, generate in CI before dry-run170- Do **not** use `workflow_dispatch` for production publish171172## Install173174```bash175# This skill only176curl -fsSL https://raw.githubusercontent.com/Melsaeed276/cursor-skills/main/skills/flutter-package-ci-pipeline/install.sh | bash177178# Or via root installer179curl -fsSL https://raw.githubusercontent.com/Melsaeed276/cursor-skills/main/scripts/install.sh | bash -s -- flutter-package-ci-pipeline180```181182Then invoke: *"Use the flutter-package-ci-pipeline skill to set up CI for this project."*183184## Additional resources185186- Composite action + workflow templates: [reference.md](reference.md)187- Per-project customization form: [project-profile.md](project-profile.md)188- Reference implementation: [anas_localization `.github/`](https://github.com/Melsaeed276/anas_localization/tree/main/.github)189- Skills collection: [github.com/Melsaeed276/cursor-skills](https://github.com/Melsaeed276/cursor-skills)