TagFlow CI

One-click Git tag deployment for Visual Studio Code.

TagFlow CI turns the four Git commands you type every time you want your CI/CD pipeline to redeploy from a moving tag into a single, validated, confirmed and verified action:

git tag -d prod
git push --delete origin refs/tags/prod
git tag prod
git push origin refs/tags/prod

Pick a repository, pick a remote, type (or pick) a tag, press Deploy Tag. TagFlow CI validates the repository, inspects the current local and remote state of the tag, shows you exactly what will happen, runs the commands strictly in order, verifies the result on the remote and records the outcome in a local history.

TagFlow CI only manages Git tags. The deployment itself is done by your CI/CD system (GitHub Actions, GitLab CI, Jenkins, …) when it reacts to the tag change.

Features

Feature	Details
Repository detection	Detects the Git repository of the active workspace, including multi-root workspaces and "parent folder with many repositories" layouts. Shows repository name, branch and commit.
Dynamic remote	Remotes are read from the selected repository (`origin`, `upstream`, `production`, …). The URL is shown without credentials.
Dynamic tag	Type any valid Git tag name or pick an existing one. Nothing is hardcoded. Names are validated with the `git check-ref-format` rules.
Sequential execution	Delete local tag → delete remote tag → create tag at HEAD → push → verify. Each step waits for the previous one; a failure stops the sequence.
Safe skips	If the local or remote tag does not exist, the deletion is skipped instead of failing.
Mandatory confirmation	A modal shows repository, branch, commit, remote, tag and the actions. Replacing an existing remote tag always requires confirmation.
State verification	The commit and the remote tag are re-checked right before mutation. If another developer moved the tag or HEAD changed, the deployment stops. After the push, the remote tag is verified; success is only reported after that.
Progress & logs	Progress notification (cancellable between steps), live step list in the sidebar, detailed logs in the TagFlow CI output channel. Credentials in remote URLs are redacted.
Presets	Save remote + tag combinations per repository (Production, Staging, …), set a default, and use Quick Deploy.
History	Local history of every attempt: time, repository, branch, commit, remote, tag, status, duration and error summary.
Error handling & safe retry	Clear messages for missing Git, missing remotes, authentication problems, protected tags, unreachable remotes and timeouts. Retry Safely re-inspects the real state before doing anything. No automatic rollback.

Requirements

Visual Studio Code 1.85 or newer.
Git on your PATH (or set tagflow.gitPath / VS Code's git.path).
Working Git authentication for the remote (Git Credential Manager, SSH keys, credential helper). TagFlow CI never stores credentials and never prompts for them; it relies on the mechanisms Git already uses.

Works on Windows, macOS and Linux, with HTTPS and SSH remotes.

Installation

From a VSIX file

Download or build tagflow-ci-<version>.vsix (see Packaging).
In VS Code open the Command Palette → Extensions: Install from VSIX… and select the file, or run from a terminal:
```
code --install-extension tagflow-ci-1.0.0.vsix
```
Reload VS Code if prompted. A TagFlow CI icon appears in the Activity Bar.

From source (development)

git clone <this repository>
cd tagflow-ci
npm install
npm run compile

Then press F5 in VS Code (launch configuration Run Extension) to start an Extension Development Host.

Usage

Entry points

Activity Bar → TagFlow CI panel (main UI).

Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description
`TagFlow CI: Deploy Tag`	Interactive flow: repository → remote → tag → confirm → deploy.
`TagFlow CI: Quick Deploy`	Deploy using a saved preset.
`TagFlow CI: Select Repository`	Choose the active repository (multi-root / multi-repo).
`TagFlow CI: Manage Presets`	Create, edit, delete presets and set the default.
`TagFlow CI: Save Current Selection as Preset`	Save the remote + tag currently selected in the sidebar.
`TagFlow CI: View Deployment History`	Browse past deployments.
`TagFlow CI: Clear Deployment History`	Remove all history entries.
`TagFlow CI: View Git Logs`	Open the output channel.
`TagFlow CI: Refresh`	Re-detect repositories and refresh Git information.

Source Control view title bar: Deploy Tag button and an overflow menu with Quick Deploy and History.
Keyboard shortcuts (customizable in Keyboard Shortcuts): Ctrl+Alt+Shift+T / Cmd+Alt+Shift+T → Deploy Tag, Ctrl+Alt+Shift+Q / Cmd+Alt+Shift+Q → Quick Deploy.

First deployment

Open a folder that contains a Git repository.
Click the TagFlow CI icon in the Activity Bar.
Check Repository, Current Branch and Target Commit.
Choose the Git Remote.
Type the Git Tag (e.g. prod) or pick an existing one from the list.
Optionally click Save Preset to reuse this combination later.
Click DEPLOY TAG.
Review the confirmation dialog and press Confirm & Deploy.
Watch the progress; when finished you get a success or failure notification with View Logs / Retry Safely.

Returning user

Open the project.
Run TagFlow CI: Quick Deploy (or select the preset in the sidebar and press DEPLOY TAG).
Confirm. Done.

What the confirmation shows

TagFlow CI — Confirm Deployment

Repository: backend-service
Branch: main
Commit: a8f31c2 — Fix payment webhook
Remote: origin (github.com/org/backend-service.git)
Tag: prod

Actions:
✓ Delete existing local tag (3f2a9c1)
✓ Delete existing remote tag (3f2a9c1)
✓ Create tag at selected commit (a8f31c2)
✓ Push tag to remote "origin"

Warning:
• Existing remote tag "prod" (3f2a9c1) will be replaced.

Deletions that do not apply are shown as – Skip … (tag does not exist …).

Execution steps and statuses

✓ Validating Git repository
✓ Checking current commit
✓ Checking existing tag
✓ Deleting local tag
✓ Deleting remote tag
✓ Creating new local tag
⟳ Pushing Git tag
○ Verifying remote tag

Statuses: Pending ○, Running ⟳, Success ✓, Failed ✗, Skipped –, Cancelled ⊘.

Settings

Setting	Default	Description
`tagflow.defaultRemote`	`"origin"`	Remote preselected for repositories you have not deployed from before.
`tagflow.defaultTag`	`""`	Tag prefilled for repositories you have not deployed from before.
`tagflow.confirmBeforeDeploy`	`true`	Show the confirmation dialog before every deployment. Replacing an existing remote tag always asks for confirmation, regardless of this setting.
`tagflow.requireCleanWorkingTree`	`true`	Block deployment when tracked files have uncommitted changes. When `false`, a warning is shown instead. Untracked files are ignored.
`tagflow.showSuccessNotification`	`true`	Show a notification after a successful deployment.
`tagflow.enableHistory`	`true`	Record deployments in the local history.
`tagflow.maxHistoryEntries`	`50`	Maximum number of history entries kept.
`tagflow.gitPath`	`""`	Path to the git executable. Falls back to VS Code's `git.path`, then `git` on `PATH`.
`tagflow.networkTimeoutSeconds`	`60`	Timeout for `ls-remote` and `push`.

How it works (and why it is safe)

Preflight — Git available, folder is a repository, tag name valid (git check-ref-format), HEAD exists, remote exists, working tree policy, detached HEAD warning.
Inspection — local tag (git rev-parse) and remote tag (git ls-remote --exit-code --tags <remote> refs/tags/<tag>). An unreachable remote or an authentication problem is reported here, before anything changes.
Confirmation — the plan you confirm is a snapshot of the exact state.
Execution — commands run one at a time through child_process.execFile with an argument array (no shell, no string interpolation), in the selected repository's directory, with GIT_TERMINAL_PROMPT=0 so a missing credential fails fast instead of hanging. Before any mutation the executor re-checks HEAD and the remote tag against the snapshot; if either changed, it stops.
Verification — after the push the remote tag is read again and must point to the target commit. Only then is the deployment marked successful.
Recovery — if a step fails (for example the remote refuses to delete a protected tag), nothing further runs. The notification and the log tell you what has and has not been done. Retry Safely runs the whole pipeline again from inspection, so deletions that are no longer needed are skipped and the tag is pushed from the verified state. TagFlow CI never force-pushes and never rolls back a remote automatically.

Tags are created as lightweight tags (git tag <name> <commit>), exactly like git tag prod.

Security

No credentials are stored or requested; Git's own authentication is used.
Remote URL credentials and well-known token formats are redacted from logs and UI.
No telemetry; nothing leaves your machine except the Git operations you confirm.
Destructive operations (remote tag deletion) always require explicit confirmation.
Server-side rules (protected tags, permissions) are respected and never bypassed.

Troubleshooting

Symptom	What to do
"Git executable … was not found"	Install Git from https://git-scm.com/downloads or set `tagflow.gitPath`.
"No Git repository was found"	Open a folder containing a repository, or use Select Repository.
"This repository has no Git remotes"	`git remote add origin <url>`
"Git authentication failed"	Configure Git Credential Manager / SSH keys; test with `git ls-remote <remote>` in a terminal.
"The remote rejected the operation"	The tag is protected or you lack permission. Ask a repository admin; TagFlow CI will not bypass this.
"Remote tag … changed since the deployment was confirmed"	Someone else moved the tag. Run the deployment again to review the new state.
Deployment cancelled after the remote tag was deleted	Use Retry Safely; the retry skips the deletion and pushes the tag.
Pipeline did not run after a successful deployment	Check that your CI/CD is configured to trigger on tag pushes / updates. TagFlow CI only updates the tag.

Open TagFlow CI: View Git Logs for the full command trace.

Development

npm install          # install dev dependencies
npm run compile      # TypeScript → out/
npm run watch        # incremental compile
npm run lint         # ESLint
npm test             # unit + integration tests (uses temporary Git repositories)
npm run test:e2e     # end-to-end tests in a real VS Code instance (see note below)
npm run icon         # regenerate media/icon.png
npm run package      # build the VSIX (runs vsce through npx; nothing to install)

Disk usage note. npm run test:e2e downloads a full VS Code build (about 1 GB including user data). It is stored in the OS temp folder (<tmp>/tagflow-ci-vscode-test), not in the project, so the repository stays small. Set TAGFLOW_VSCODE_TEST_CACHE to use another location, and delete that folder whenever you want the space back. node_modules/ (about 56 MB) is only needed for development; end users only need the VSIX file (about 70 KB).

Project structure

tagflow-ci/
├── src/
│   ├── extension.ts              # activation, wiring, public API
│   ├── controller.ts             # shared state + deployment pipeline
│   ├── commands/                 # Deploy Tag, Quick Deploy, presets, history
│   ├── services/
│   │   ├── gitService.ts         # safe Git CLI wrapper (execFile, serialized)
│   │   ├── repositoryService.ts  # repository discovery and snapshots
│   │   ├── tagService.ts         # tag validation and state inspection
│   │   ├── deploymentService.ts  # preflight, planning, sequential executor
│   │   ├── presetService.ts
│   │   └── historyService.ts
│   ├── providers/sidebarProvider.ts   # Activity Bar webview
│   ├── storage/presetStorage.ts
│   ├── ui/                       # prompts, notifications, progress, output channel
│   ├── utils/                    # validation, error mapping, redaction, logger
│   └── types/
├── media/                        # icon.svg, icon.png, sidebar.css, sidebar.js
├── test/
│   ├── unit/                     # pure unit tests (no VS Code, no Git)
│   ├── integration/              # real Git in temporary repositories
│   └── e2e/                      # @vscode/test-electron
├── package.json
└── README.md

The services, storage, utils and types folders do not import vscode, which is what makes the Git engine testable with plain Mocha.

Testing

Unit tests cover tag/remote validation, command argument generation, error mapping, credential redaction, tag state comparison, preset storage, history and the deployment planner.
Integration tests create a bare "remote" repository and a working clone in a temporary directory and run the real engine against them: new tag, tag update, custom remote and tag, protected tag (receive.denyDeletes), unreachable remote, dirty working tree, concurrent deployment lock, race conditions (remote tag or HEAD changed after confirmation), cancellation + safe retry, annotated tag replacement, and log redaction. They never touch a real repository.
End-to-end tests start VS Code with the extension and a temporary workspace and check activation, command registration, configuration and repository detection.

Packaging

npm run package
# → tagflow-ci-1.0.0.vsix

To share the extension with other people, send them only the .vsix file. They install it with Extensions: Install from VSIX… or code --install-extension tagflow-ci-1.0.0.vsix. An Indonesian step-by-step guide is in INSTALL-ID.md.

Publishing to the Marketplace

The extension is published under the publisher id Sana (Sana.tagflow-ci). The full procedure (publisher account, Personal Access Token, npm run publish, release workflow) is in PUBLISHING.md. Once published, users can install it from the Extensions view by searching for TagFlow CI.

Roadmap

v1.1 — tag autocomplete improvements, richer sidebar, more keyboard shortcuts.
v1.2 — annotated tags, custom target commit, commit diff preview, advanced protected-tag safeguards.
v2.0 — CI/CD platform integration (GitHub Actions, GitLab CI, Jenkins, Bitbucket): pipeline status and logs inside VS Code.

License

MIT — see the LICENSE file in this repository.