|
| 1 | +--- |
| 2 | +title: Branch management |
| 3 | +description: Launcher label, naming conventions, and when branches are created (including hotfix and release). |
| 4 | +--- |
| 5 | + |
| 6 | +# Branch management |
| 7 | + |
| 8 | +Copilot creates **branches** for issues when the right **labels** are present. For most issue types (feature, bugfix, docs, chore), a **launcher label** (e.g. `branched`) is required unless you set **`branch-management-always: true`**. For **hotfix** and **release**, the branch is created as soon as the type label is present (and the issue creator is a member). This page details the launcher, naming, and special rules. |
| 9 | + |
| 10 | +## Launcher label (when to create the branch) |
| 11 | + |
| 12 | +For **feature**, **bugfix**, **docs**, and **chore** issues, the action does **not** create a branch on issue open by default. A member must add a **launcher label** to trigger branch creation. |
| 13 | + |
| 14 | +| Input | Default | Description | |
| 15 | +|-------|---------|-------------| |
| 16 | +| **`branch-management-launcher-label`** | `branched` | Label that triggers branch creation when added to an issue that already has a type label (feature, bugfix, docs, chore). | |
| 17 | +| **`branch-management-always`** | `false` | If `true`, the action **ignores** the launcher label: it creates the branch as soon as the issue has a type label (e.g. on open or when the type label is added). | |
| 18 | + |
| 19 | +### Example: use the default launcher |
| 20 | + |
| 21 | +Workflow: |
| 22 | + |
| 23 | +```yaml |
| 24 | +- uses: vypdev/copilot@v1 |
| 25 | + with: |
| 26 | + token: ${{ secrets.PAT }} |
| 27 | + branch-management-launcher-label: branched |
| 28 | +``` |
| 29 | +
|
| 30 | +Flow: Open issue with label `feature` → no branch yet. Add label `branched` → branch `feature/123-title` is created from `develop`. |
| 31 | + |
| 32 | +### Example: create branch without launcher |
| 33 | + |
| 34 | +```yaml |
| 35 | +- uses: vypdev/copilot@v1 |
| 36 | + with: |
| 37 | + token: ${{ secrets.PAT }} |
| 38 | + branch-management-always: true |
| 39 | +``` |
| 40 | + |
| 41 | +Flow: Open issue with label `feature` → branch is created immediately (no need to add `branched`). |
| 42 | + |
| 43 | +## Naming conventions |
| 44 | + |
| 45 | +Branch names follow **`<tree>/<issue-number>-<slug>`**. The **tree** is the prefix for the issue type; the **slug** is derived from the issue title (sanitized). You can configure main branch, development branch, and each tree. |
| 46 | + |
| 47 | +| Input | Default | Description | |
| 48 | +|-------|---------|-------------| |
| 49 | +| `main-branch` | `master` | Main production branch (used as base for hotfix). | |
| 50 | +| `development-branch` | `develop` | Development branch (used as base for feature, bugfix, docs, chore, release). | |
| 51 | +| `feature-tree` | `feature` | Prefix for feature branches. | |
| 52 | +| `bugfix-tree` | `bugfix` | Prefix for bugfix branches. | |
| 53 | +| `docs-tree` | `docs` | Prefix for docs branches. | |
| 54 | +| `chore-tree` | `chore` | Prefix for chore branches. | |
| 55 | +| `hotfix-tree` | `hotfix` | Prefix for hotfix branches. | |
| 56 | +| `release-tree` | `release` | Prefix for release branches. | |
| 57 | + |
| 58 | +### Example branch names |
| 59 | + |
| 60 | +- `feature/123-add-user-login` |
| 61 | +- `bugfix/456-fix-null-check` |
| 62 | +- `hotfix/789-critical-payment-fix` |
| 63 | +- `release/10-v1-2-0` |
| 64 | + |
| 65 | +Use **`commit-prefix-transforms`** (e.g. `replace-slash`) so commit message prefixes match your conventions (e.g. `feature-123-add-user-login`). See [Configuration](/configuration). |
| 66 | + |
| 67 | +### Example: custom naming |
| 68 | + |
| 69 | +```yaml |
| 70 | +- uses: vypdev/copilot@v1 |
| 71 | + with: |
| 72 | + token: ${{ secrets.PAT }} |
| 73 | + main-branch: main |
| 74 | + development-branch: dev |
| 75 | + feature-tree: feat |
| 76 | + bugfix-tree: fix |
| 77 | +``` |
| 78 | + |
| 79 | +Branches would be e.g. `feat/123-add-login` and `fix/456-fix-bug`, created from `dev` (or `main` for hotfix). |
| 80 | + |
| 81 | +## Hotfix and release: no launcher needed |
| 82 | + |
| 83 | +For **hotfix** and **release**: |
| 84 | + |
| 85 | +- The branch is created **without** requiring the launcher label. As soon as the issue has the `hotfix` or `release` label (and the creator is a member), the action creates the branch. |
| 86 | +- **Hotfix** branches are created from **`main-branch`** (at the latest tag). |
| 87 | +- **Release** branches are created from **`development-branch`**. |
| 88 | +- If a **non-member** opens a hotfix or release issue, the action **closes** the issue to avoid accidental production/release flows. |
| 89 | + |
| 90 | +Adding the **`deploy`** label to a release or hotfix issue **triggers** the workflow named in `release-workflow` or `hotfix-workflow`. Ensure those workflow **filenames** match exactly (e.g. `release_workflow.yml`, `hotfix_workflow.yml`). See [Labels and branch types](/issues/labels-and-branch-types). |
| 91 | + |
| 92 | +## Emoji in issue title |
| 93 | + |
| 94 | +When **`emoji-labeled-title`** is `true` (default), the action can update the issue title to include an emoji based on labels (e.g. 🧑💻 when branched). The **`branch-management-emoji`** input (default: 🧑💻) is the emoji used for branched issues. See [Configuration](/issues/configuration). |
| 95 | + |
| 96 | +## Next steps |
| 97 | + |
| 98 | +- **[Labels and branch types](/issues/labels-and-branch-types)** — Which labels create which branches. |
| 99 | +- **[Workflow setup](/issues/workflow-setup)** — Enable the action for issue events. |
| 100 | +- **[Issue types](/issues/type/feature)** — Per-type details (source branch, naming, deploy). |
0 commit comments