v2.0

What's Changed

• Improve Action Reliability by @rmottanet in #2
• Architectural Refactoring by @rmottanet in #3

Full Changelog: v1.0...v2.0

v1 - Initial Release

Just so you know – the initial stable release of Branch Spawn is now available. This GitHub Action enables the automated creation of new branches within any GitHub repository, supporting workflows that require systematic branching strategies such as feature isolation, hotfix operations, and release preparation across CI/CD pipelines.

---

✨ Core Functionality and Architecture

The Action executes within an isolated Node.js environment (runs: using: 'node20') and interacts with the GitHub Git Data API via the official Octokit client. The branch creation flow is implemented as a two-step, atomic operation:

1. Source Reference Retrieval:
   The Action queries the base branch to obtain its latest commit SHA (via GET /git/ref/heads/{base-branch}).

2. New Reference Creation:
   A new branch reference is created using the retrieved SHA (via POST /git/refs), establishing the new branch at the exact state of the source branch.

Required Parameters

Execution depends on the mandatory declaration of all input parameters defined in action.yml:

• owner: Repository owner (user or organization).
• repo: Target repository name.
• base-branch: Existing branch to be used as the creation source.
• new-branch: Name of the branch that will be created.
• github-token: Token with contents: write permission, ideally a PAT for cross-repository support.

---

🚀 Implementation and Integration

This Action can be integrated into any GitHub workflow with minimal configuration. It is commonly used in release automation, standardization of naming conventions, or multi-repository orchestration scenarios. Below is a typical workflow example leveraging workflow_dispatch to provide runtime input validation and flexibility.

Example Workflow (.github/workflows/branch_spawn.yml):

name: Branch Spawn Utility

on:
  # Execution is initiated manually with runtime parameters.
  workflow_dispatch:
    inputs:
      owner:
        description: 'Repository Owner'
        required: true
        default: ${{ github.repository_owner }}
      repo:
        description: 'Repository Name'
        required: true
        default: ${{ github.event.repository.name }}
      base_branch:
        description: 'Source Branch Reference'
        required: true
      new_branch:
        description: 'New Branch Reference'
        required: true

jobs:
  exec_branch_spawn:
    runs-on: ubuntu-latest
    permissions:
      # Required to create new references in the target repository.
      contents: write
    steps:
      - name: Execute Branch Spawn Operation
        uses: ws2git/branch-spawn@v1
        
        with:
          github-token: ${{ secrets.YOUR_PAT }} # Strongly recommended for cross-repo access
          owner: ${{ github.event.inputs.owner }}
          repo: ${{ github.event.inputs.repo }}
          base-branch: ${{ github.event.inputs.base_branch }}
          new-branch: ${{ github.event.inputs.new_branch }}

---

🛡️ Authentication and Authorization

Because branch creation requires explicit write permissions to repository contents, proper token provisioning is essential.
While the default ${{ github.token }} may be adequate for operations within the same repository, it often lacks the required scope for:

• Cross-repository branch creation
• Organization-level repositories with restricted permissions
• Automated release pipelines with elevated security standards

A Personal Access Token (PAT) with repo or contents: write permission is strongly recommended, and it should always be provided via secure GitHub Secrets (e.g., secrets.YOUR_PAT).

---

🔗 Documentation and Support

For full details on inputs, execution flow, and integration guidance, refer to the primary [README.md](https://github.com/ws2git/branch-spawn/blob/main/README.md).

Issues, feature requests, and enhancement proposals can be submitted via the project’s [Issue Tracker](https://github.com/ws2git/branch-spawn/issues).

---