Skip to content

Commit 67e67ed

Browse files
rmottanetrmottanet
authored
Introducing... (#1)
* feat(action): defines the initial metadata, inputs, and outputs of the action. Configures the inputs (, etc.) and outputs. Defines the main entry point ( in ). * feat(core): Implements the main greeting logic of the action. Adds the `src/main.ts` file containing the main function. Uses `@actions/core` to get inputs and define outputs. Includes basic error handling with `try/catch`. * style(config): Configures TypeScript compiler options. Defines `target` for es2020 and `module` for commonjs. Enables `strict` and `esModuleInterop` for good typing and import practices. * build(deps): Configures the TypeScript environment and dependencies. Adds necessary development dependencies: TypeScript, @types/node, ESLint. Configures scripts for build, lint, and packaging (`ncc`). * chore(deps): Updates dependency locking after installation Ensures reproducibility by locking dependency versions in package-lock.json. * build(dist): Updates distribution artifact after compilation This commit updates the dist/index.js file after the build and package script runs, ensuring that the Action uses the latest version of the source code (src/). * Enhance README with usage and security details Expanded README to include detailed usage instructions, features, and security recommendations for the GitHub Action.
1 parent 8f32a28 commit 67e67ed

File tree

7 files changed

+32486
-1
lines changed

7 files changed

+32486
-1
lines changed

‎README.md‎

Lines changed: 137 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,139 @@
11
# Branch Shift
22

3-
GitHub Action in TypeScript to quickly rename branches via GitHub API, automating branch management in repositories.
3+
This GitHub Action renames an existing branch in a GitHub repository using the GitHub API (via a Node.js script).
4+
This is useful for teams who want to **automate branch maintenance or enforce naming conventions** in their CI/CD workflows.
5+
6+
---
7+
8+
## ✨ Features
9+
10+
- **Rename Capability**: Safely renames a specific branch to a new name.
11+
- **Simple Integration**: One-step usage in any workflow.
12+
- **API Driven**: Performs the operation using the GitHub API, ensuring reliability.
13+
- **Flexible**: Requires standard branch name, new name, repository owner, and repository name as inputs.
14+
15+
16+
## 🛠️ Usage
17+
18+
### 1. **Prerequisites**
19+
20+
- Your workflow **must pass all the necessary inputs** (owner, repo, branch, new_name) to this action.
21+
- The environment variable `GH_TOKEN` must be set to a valid GitHub token with the required **write permissions** for the repository, specifically to **edit repository contents/branches**.
22+
* **Recommendation:** Use a **PAT (Personal Access Token) Secret** with `repo` scope for maximum reliability, as the default `${{ github.token }}` might not have the required permissions to rename branches in all repository security settings.
23+
24+
### 2. **Example Workflow Integration**
25+
26+
```yaml
27+
name: Rename Branch
28+
29+
on:
30+
workflow_dispatch:
31+
inputs:
32+
owner:
33+
description: 'Proprietário do Repositório (Ex: sua-org ou seu-usuario)'
34+
required: true
35+
default: '{{ github.repository_owner }}' # Sugestão: Preencher automaticamente com o owner atual
36+
37+
repo:
38+
description: 'Nome do Repositório (Ex: meu-projeto)'
39+
required: true
40+
default: '{{ github.event.repository.name }}' # Sugestão: Preencher automaticamente com o repo atual
41+
42+
branch:
43+
description: 'Nome da Branch Atual (para ser renomeada)'
44+
required: true
45+
46+
new_name:
47+
description: 'Novo Nome para a Branch'
48+
required: true
49+
50+
jobs:
51+
exec_rename:
52+
runs-on: ubuntu-latest
53+
steps:
54+
- name: Exec Branch Shift
55+
uses: ws2git/branch-shift@v1
56+
57+
with:
58+
github_token: ${{ secrets.YOUR_PAT }}
59+
owner: ${{ github.event.inputs.owner }}
60+
repo: ${{ github.event.inputs.repo }}
61+
branch: ${{ github.event.inputs.branch }}
62+
new_name: ${{ github.event.inputs.new_name }}
63+
````
64+
65+
66+
## 📥 Inputs
67+
68+
| Name | Required | Description |
69+
|---|---|---|
70+
| `github_token` | Yes | GitHub Token with `repo` scope to authorize the API call. |
71+
| `owner` | Yes | The owner of the repository (e.g., your-organization or your-username). |
72+
| `repo` | Yes | The name of the repository (e.g., your-repo). |
73+
| `branch` | Yes | The current name of the branch to be renamed. |
74+
| `new_name` | Yes | The new desired name for the branch. |
75+
76+
77+
## ⚙️ How It Works
78+
79+
This action executes a **Node.js script** (`dist/index.js`) that uses the GitHub API to perform two main steps to effectively "rename" a branch:
80+
81+
1. **Create a New Branch:** It creates a new branch using the `new_name` that points to the same commit as the `branch` (the old name).
82+
2. **Delete the Old Branch:** It deletes the original `branch` (the old name).
83+
84+
The use of a Node.js script allows for precise control over the API calls.
85+
86+
**Script logic (Conceptual):**
87+
88+
```javascript
89+
// Step 1: Create a new branch pointing to the old branch's commit SHA
90+
const create_ref_url = `/repos/${owner}/${repo}/git/refs`;
91+
// API Call: POST /repos/{owner}/{repo}/git/refs
92+
// Body: { "ref": "refs/heads/new_name", "sha": <SHA_of_old_branch> }
93+
94+
// Step 2: Delete the old branch
95+
const delete_ref_url = `/repos/${owner}/${repo}/git/refs/heads/${branch}`;
96+
// API Call: DELETE /repos/{owner}/{repo}/git/refs/heads/branch
97+
98+
```
99+
100+
If **any required parameter is missing** or the **token lacks the necessary permissions**, the script will exit with an error.
101+
102+
103+
## 🛡️ Security and Authentication
104+
105+
This Action requires a GitHub Token with **write permissions** on the repository to perform branch operations. The token is passed via the **`github_token` input**.
106+
107+
**Recommended**: Since renaming a branch is a highly privileged operation, it's highly recommended to use a **Personal Access Token (PAT)** stored as a **Secret** that explicitly has the `repo` scope, as the default **`${{ github.token }}`** might not have sufficient permissions, especially in organizational setups.
108+
109+
```yaml
110+
env:
111+
# Using an explicitly created Secret PAT (e.g., REPO_RENAME_TOKEN)
112+
# stored in your repository secrets.
113+
GH_TOKEN: ${{ secrets.REPO_RENAME_TOKEN }}
114+
```
115+
116+
**Never expose the PAT in plain text.**
117+
118+
119+
## 📌 Notes
120+
121+
⚠️ Attention: Repository Access Permissions
122+
123+
**It is crucial to ensure that the token used has the `repo` scope or the necessary permissions to *push* and *delete* branches.** This is often the biggest hurdle for branch manipulation Actions.
124+
125+
These are the important points to consider regarding the branch renaming operation:
126+
127+
* **Default Token Limitation**: The default token (`${{ github.token }}`) might be read-only or lack the necessary permissions to delete or create branches via the API, especially in certain contexts (like PRs from forks) or with stricter organization security settings.
128+
* **PAT is Safer**: For Actions that modify the repository structure (like renaming/deleting branches), using a **dedicated PAT stored as a secret** is the most reliable approach.
129+
130+
131+
## 🔗 Related Documentation
132+
133+
* [GitHub Actions Contexts](https://docs.github.com/en/actions/learn-github-actions/contexts)
134+
* [GitHub REST API - Rename a Branch](https://docs.github.com/en/rest/branches/branches?apiVersion=2022-11-28#rename-a-branch)
135+
136+
137+
## ❓ Support
138+
139+
If you find a bug or have a question, [open an issue](https://github.com/ws2git/branch-shift/issues).

‎action.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: 'Branch Shift'
2+
description: 'Renames a branch using the GitHub API'
3+
author: 'rmottanet'
4+
branding:
5+
icon: 'git-branch'
6+
color: 'orange'
7+
inputs:
8+
github_token:
9+
description: 'GitHub Token'
10+
required: true
11+
owner:
12+
description: 'Repository owner'
13+
required: true
14+
repo:
15+
description: 'Repository name'
16+
required: true
17+
branch:
18+
description: 'Current branch name'
19+
required: true
20+
new_name:
21+
description: 'New branch name'
22+
required: true
23+
24+
runs:
25+
using: 'node16'
26+
main: 'dist/index.js'

0 commit comments

Comments
 (0)