GitTools · SimplyAName · Oct 25, 2025 · Oct 14, 2025
diff --git a/.gitignore b/.gitignore
@@ -8,6 +8,7 @@ pnpm-debug.log*
 lerna-debug.log*
 
 node_modules
+
 #dist
 dist-ssr
 *.local
@@ -35,3 +36,6 @@ dist-ssr
 junit-report.xml
 
 src/__tests__/test.env
+
+# Unit test files
+test.env
diff --git a/README.md b/README.md
@@ -4,8 +4,8 @@
 
 GitHub Actions that allow the setup and use of the [GitVersion](https://github.com/GitTools/GitVersion) and [GitReleaseManager](https://github.com/GitTools/GitReleaseManager) tools.
 
-[![Build Status](https://github.com/GitTools/actions/workflows/CI/badge.svg)](https://github.com/GitTools/actions/actions)
-[![Build Status](https://github.com/GitTools/actions/workflows/release/badge.svg)](https://github.com/GitTools/actions/actions)
+[![CI Build Status](https://github.com/GitTools/actions/workflows/CI/badge.svg)](https://github.com/GitTools/actions/actions)
+[![Release Build Status](https://github.com/GitTools/actions/workflows/release/badge.svg)](https://github.com/GitTools/actions/actions)
 
 [![GitHub Release](https://img.shields.io/github/v/release/gittools/actions?logo=github&sort=semver)](https://github.com/GitTools/actions/releases/latest)
 
@@ -39,3 +39,104 @@ Examples for usage of **GitReleaseManager**:
 ### Versioning and Compatibility
 
 You can find the compatibility matrix in the [versions.md](docs/versions.md) file.
+
+## Contributing
+
+### Prerequisites
+
+1. **Linux** - Recommended to build and run
+2. **Node.js** - Latest LTS version recommended
+3. **.NET SDK** - Version 6.0 or later required for GitVersion and GitReleaseManager tools
+4. **Git** - Latest version recommended
+
+### Development Environment Setup
+
+This project is design to be run and worked on in a Linux environment.
+If developing on Windows, please consider using WSL as it's likely you will run issues with file paths etc
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/GitTools/actions.git
+   cd actions
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Build the project:
+   - For local development: `npm run build:local`
+   - For Azure Pipelines: `npm run build:azure`
+   - For GitHub Actions: `npm run build:github`
+
+4. Test the project:
+
+   ```bash
+   npm run test
+   ```
+
+### Required Knowledge
+
+- **TypeScript/JavaScript** - Primary development languages
+- **GitHub Actions** - Understanding of action creation and workflows
+- **Azure Pipelines** - Familiarity with pipeline tasks and extensions
+- **.NET Tools** - Basic understanding of .NET CLI tools
+- **Git** - Strong knowledge of Git versioning and release management
+
+### Project Structure
+
+- `src/tools/` - Core implementation of GitVersion and GitReleaseManager integrations
+- `src/agents/` - Build agent implementations for different CI platforms
+- `src/__tests__/` - Test suites organized by component
+- `docs/examples/` - Usage examples for both GitHub Actions and Azure Pipelines
+
+### Creating Pull Requests
+
+When contributing to this project, please follow these guidelines for creating pull requests:
+
+1. **Fork and Clone**
+   - Fork the repository to your GitHub account
+   - Clone your fork locally: `git clone https://github.com/YOUR-USERNAME/actions.git`
+   - Add upstream remote: `git remote add upstream https://github.com/GitTools/actions.git`
+
+2. **Create a Feature Branch**
+   - Create a branch from main: `git checkout -b feature/your-feature-name`
+   - Use descriptive branch names (e.g., `feature/add-new-version-format`, `fix/issue-123`)
+
+3. **Keep Your Branch Updated**
+   - Fetch upstream changes: `git fetch upstream`
+   - Rebase your branch on upstream main:
+
+     ```bash
+     git checkout main
+     git rebase upstream/main
+     git checkout your-branch
+     git rebase main
+     ```
+
+   - Always use rebase instead of merge to maintain a clean history
+
+4. **Make Your Changes**
+   - Make commits with clear, descriptive messages
+   - Follow the project's code style and conventions
+   - Add tests for new features or bug fixes
+   - Run tests locally to ensure everything passes
+
+5. **Submit the Pull Request**
+   - Push your changes to your fork: `git push origin your-branch`
+   - Go to the original repository on GitHub
+   - Click "New Pull Request" and select your feature branch
+   - Link any related issues
+
+6. **PR Guidelines**
+   - Keep PRs focused and single-purpose
+   - Include tests and documentation updates
+   - Ensure CI checks pass
+
+7. **After PR is Merged**
+   - Delete your feature branch locally and remotely
+   - Update your main branch with the upstream changes
+   - Celebrate your contribution! 🎉
diff --git a/dist/tools/lib.mjs b/dist/tools/lib.mjs
@@ -24,6 +24,18 @@ async function run(agent, tool, command) {
   const runner = await getToolRunner(agent, tool);
   return await runner.run(command);
 }
+function allIndexesOf(searchString, indexOf) {
+  if (indexOf.length !== 1) {
+    throw new Error("indexOf must be a single character");
+  }
+  const resultArray = [];
+  for (let i = 0; i < searchString.length; i++) {
+    if (searchString[i] === indexOf) {
+      resultArray.push(i);
+    }
+  }
+  return resultArray;
+}
 
-export { getAgent, getToolRunner, parseCliArgs, run };
+export { allIndexesOf, getAgent, getToolRunner, parseCliArgs, run };
 //# sourceMappingURL=lib.mjs.map
diff --git a/dist/tools/lib.mjs.map b/dist/tools/lib.mjs.map
diff --git a/dist/tools/libs/gitversion.mjs b/dist/tools/libs/gitversion.mjs
@@ -4,6 +4,7 @@ import 'node:fs/promises';
 import 'node:os';
 import 'node:path';
 import './semver.mjs';
+import { allIndexesOf } from '../lib.mjs';
 
 class GitVersionSettingsProvider extends SettingsProvider {
   getExecuteSettings() {
@@ -202,35 +203,67 @@ class Runner extends RunnerBase {
   async execute() {
     return this.safeExecute(async () => {
       const result = await this.tool.executeJson();
-      this.buildAgent.debug("Parsing GitVersion output");
       return this.processGitVersionOutput(result);
     }, "GitVersion executed successfully");
   }
   async command() {
     return this.safeExecute(async () => await this.tool.executeCommand(), "GitVersion executed successfully");
   }
   processGitVersionOutput(result) {
-    if (result.code === 0) {
-      const stdout = result.stdout;
-      if (stdout.lastIndexOf("{") === -1 || stdout.lastIndexOf("}") === -1) {
-        const errorMessage = "GitVersion output is not valid JSON, see output details";
+    this.buildAgent.debug("Parsing GitVersion output");
+    if (result.code !== 0) {
+      return result;
+    }
+    const stdout = result.stdout;
+    const gitVersionOutput = this.extractGitVersionOutput(stdout);
+    if (gitVersionOutput === null) {
+      const errorMessage = "GitVersion output is not valid JSON, see output details";
+      this.buildAgent.debug(errorMessage);
+      this.buildAgent.setFailed(errorMessage, true);
+      return {
+        code: -1,
+        error: new Error(errorMessage)
+      };
+    }
+    this.tool.writeGitVersionToAgent(gitVersionOutput);
+    this.tool.updateBuildNumber();
+    this.buildAgent.setSucceeded("GitVersion executed successfully", true);
+    return result;
+  }
+  /**
+   * Attempts to extract and parse a JSON object representing `GitVersionOutput` from the given input string.
+   * The method assumes the last closing curly brace (`}`) in the input belongs to the end of the JSON object,
+   * and iteratively expands the search area backwards from each opening curly brace (`{`) until a valid JSON object is found.
+   * If parsing fails, it logs debug information and continues searching until all possible start positions are exhausted.
+   *
+   * @param input - The string containing the potential JSON output from GitVersion.
+   * @returns The parsed `GitVersionOutput` object if extraction and parsing succeed; otherwise, `null`.
+   */
+  extractGitVersionOutput(input) {
+    const allStartOfJsonIndexes = allIndexesOf(input, "{");
+    const endOfJsonIndex = input.lastIndexOf("}") + 1;
+    let startIndexArrayPos = allStartOfJsonIndexes.length - 1;
+    let decodePassCount = 1;
+    let currSearchString = input.substring(allStartOfJsonIndexes[startIndexArrayPos], endOfJsonIndex);
+    let resultJson = null;
+    while (resultJson === null && startIndexArrayPos >= 0) {
+      try {
+        this.buildAgent.debug(`Starting JSON extraction at ${allStartOfJsonIndexes[startIndexArrayPos]} to ${endOfJsonIndex}`);
+        resultJson = JSON.parse(currSearchString);
+      } catch (ex) {
+        let exObject = new Error("Unable to parse exception object");
+        if (ex instanceof Error) {
+          exObject = ex;
+        }
+        const errorMessage = `Failed to parse JSON object on pass ${decodePassCount}. Expanding search area from string index ${allStartOfJsonIndexes[startIndexArrayPos]} to ${endOfJsonIndex}
+Caught Exception: ${exObject.message}`;
         this.buildAgent.debug(errorMessage);
-        this.buildAgent.setFailed(errorMessage, true);
-        return {
-          code: -1,
-          error: new Error(errorMessage)
-        };
-      } else {
-        const jsonOutput = stdout.substring(stdout.lastIndexOf("{"), stdout.lastIndexOf("}") + 1);
-        const gitVersionOutput = JSON.parse(jsonOutput);
-        this.tool.writeGitVersionToAgent(gitVersionOutput);
-        this.tool.updateBuildNumber();
-        this.buildAgent.setSucceeded("GitVersion executed successfully", true);
-        return result;
+        decodePassCount++;
+        startIndexArrayPos--;
+        currSearchString = input.substring(allStartOfJsonIndexes[startIndexArrayPos], endOfJsonIndex);
       }
-    } else {
-      return result;
     }
+    return resultJson;
   }
 }
 

diff --git a/dist/tools/libs/gitversion.mjs.map b/dist/tools/libs/gitversion.mjs.map