MENU

Dependabotブランチ名のカスタマイズ方法｜prefix・最大長・template設定を解説

WEBサービス

GitHub Dependabotが作成するプルリクエストのブランチ名は、.github/dependabot.ymlのpull-request-branch-nameでカスタマイズできます。prefix、separator、max-length、word-separator、branch-name-case、templateを組み合わせれば、CI/CDの命名規則や文字数制限に合わせたブランチ名を生成できます。

たとえば、既定のdependabot/npm_and_yarn/Lodash-4.17.21を、dependabot-npm-and-yarn-lodash-4.17.21のように、スラッシュなし・小文字・ハイフン区切りの形式へ変更できます。まずはseparator、word-separator、branch-name-case、max-lengthを設定し、構造そのものを変えたい場合だけtemplateを追加する方法が安全です。

この機能拡張は2026年8月4日に発表され、GitHub.comの全ユーザーが利用できます。GitHub Enterprise Serverでは、GHES 3.23に収録予定と案内されています。(The GitHub Blog)

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

Dependabotのブランチ名カスタマイズで解決できること

Dependabotのブランチ名は、既定ではdependabot/PACKAGE-MANAGER/DEPENDENCYを基本とした形式で生成されます。実際には、次のような名前になります。

dependabot/npm_and_yarn/Lodash-4.17.21

この形式で問題がなければ、設定を変更する必要はありません。一方、ブランチ名をDockerイメージのタグに流用している場合や、外部CIが特定の正規表現だけを受け付ける場合は、スラッシュ、大文字、アンダースコア、文字数が問題になることがあります。GitHubも、CI/CDの命名規則や長さ制限、モノレポでの識別性を主な用途として挙げています。(The GitHub Blog)

実務上の問題使用する設定対応内容
/を含むブランチ名を使えないseparatorセグメント間の/を-などに変更する
npm_and_yarnの_を使えないword-separatorブランチ名内部の_を-などに置き換える
依存関係名に大文字が含まれるbranch-name-caseプレフィックス以降を小文字または大文字に統一する
ブランチ名がCIの上限を超えるmax-length最大文字数で切り詰める
dependabot以外の接頭辞を使いたいprefixdepsやbot-depsなどに変更する
要素の順番や構造を変えたいtemplateプレースホルダーを使って形式を定義する

pull-request-branch-nameで指定できる項目

pull-request-branch-nameでは、次の6項目を利用できます。

項目既定値主な制限役割
separator"/"使用可能値は"-"、"_"、"/"ブランチ名のセグメント間にある/を置換する
prefix"dependabot"最大50文字ブランチ名の先頭文字列を変更する
max-length10020～244ブランチ名の最大文字数を指定する
word-separator未設定生成結果が有効なGit参照名であることプレフィックス以降の_を置換する
branch-name-case未設定"lowercase"または"uppercase"プレフィックス以降の大文字・小文字を統一する
template未設定最大200文字ブランチ名の構造をプレースホルダーで定義する

max-lengthを超えた場合は単純に末尾が削除されるのではなく、一意性を維持するためのハッシュサフィックスが付加されます。(GitHub Docs)

最短でCI規則に合わせる設定例

ブランチ名を「小文字・ハイフン区切り・80文字以内」に統一する場合は、次の設定が使いやすいでしょう。

version: 2

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

    pull-request-branch-name:
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80

この設定では、ブランチ名が次のように変わります。

設定前設定後
dependabot/npm_and_yarn/Lodash-4.17.21dependabot-npm-and-yarn-lodash-4.17.21

separatorだけでは、npm_and_yarnに含まれるアンダースコアは残ります。アンダースコアもハイフンへ変更したい場合は、word-separatorも同時に指定してください。(GitHub Docs)

また、separatorにハイフンを指定するときは、次のように引用符で囲みます。

separator: "-"

separator: -と記述すると、YAMLのリスト開始として誤って解釈される可能性があります。(GitHub Docs)

prefix・separator・最大長を正しく使い分ける

prefixでブランチ名の先頭を変更する

prefixは、既定のdependabotを別の文字列へ変更する設定です。

pull-request-branch-name:
  prefix: "deps"

生成されるブランチ名は、次のようになります。

deps/npm_and_yarn/lodash-4.17.21

複数の自動更新ツールを使用している場合は、deps、renovate、security-depsなど、用途が分かる名前に統一できます。

ただし、既存のCIや自動マージ処理がdependabot/で始まるブランチだけを対象にしている場合、prefixを変更すると条件に一致しなくなります。設定変更前に、ワークフロー、外部CI、シェルスクリプト、ブランチルールからdependabot/という文字列を検索してください。

prefixは最大50文字です。また、後述するbranch-name-caseの変換対象はプレフィックスより後ろであるため、プレフィックスの大文字・小文字は指定したまま残ります。(GitHub Docs)

separatorとword-separatorは置換対象が異なる

名前が似ていますが、2つの設定は置換する文字の位置が異なります。

dependabot / npm_and_yarn / Lodash-4.17.21
           ↑                ↑
       separator       word-separator

separatorは、ブランチ名を構成するセグメント間の/を変更します。

pull-request-branch-name:
  separator: "-"

結果は次のとおりです。

dependabot-npm_and_yarn-Lodash-4.17.21

一方、word-separatorは、プレフィックスより後ろにある_を変更します。

pull-request-branch-name:
  word-separator: "-"

結果は次のようになります。

dependabot/npm-and-yarn/Lodash-4.17.21

スラッシュとアンダースコアの両方をなくしたい場合は、2項目を同時に指定します。

pull-request-branch-name:
  separator: "-"
  word-separator: "-"

word-separatorは、パッケージマネージャー名だけでなく、依存関係名、グループ名、ディレクトリパスなど、プレフィックス以降に含まれるアンダースコアにも適用されます。(GitHub Docs)

branch-name-caseで小文字または大文字に統一する

依存関係名に大文字が含まれると、ブランチ名から作成したDockerタグやCI用識別子が命名規則に違反することがあります。

すべて小文字に統一する場合は、次のように設定します。

pull-request-branch-name:
  branch-name-case: "lowercase"
dependabot/npm_and_yarn/Lodash-4.17.21
↓
dependabot/npm_and_yarn/lodash-4.17.21

使用できる値は次の2つです。

設定値動作
"lowercase"プレフィックス以降を小文字にする
"uppercase"プレフィックス以降を大文字にする

変換対象はプレフィックスより後ろです。たとえば、prefix: "DEPS"とbranch-name-case: "lowercase"を組み合わせても、DEPS自体は小文字に変換されません。(GitHub Docs)

max-lengthでブランチ名の長さを制限する

max-lengthでは、Dependabotが生成するブランチ名の最大文字数を指定できます。

pull-request-branch-name:
  max-length: 60

指定できる範囲は20～244文字で、既定値は100文字です。指定した長さを超えた場合は、一意性を保つためのハッシュを含む形で切り詰められます。(GitHub Docs)

外部システムの上限が80文字の場合、Dependabot側も80文字に設定できます。ただし、そのブランチ名の前後へ別の識別子を追加する処理があるなら、上限いっぱいではなく60～70文字程度に抑える方法が安全です。

たとえば、CIが次の文字列を連結する場合があります。

repository-name-branch-name-build-number

この場合、ブランチ名だけを80文字にすると、連結後のタグやジョブ名が上限を超える可能性があります。最終的に利用するDockerタグ、キャッシュキー、アーティファクト名まで含めて長さを決めてください。

templateでブランチ名の構造を指定する

templateを使用すると、単なる文字置換ではなく、ブランチ名に含める情報と順番を指定できます。

version: 2

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

    pull-request-branch-name:
      prefix: "deps"
      template: "{prefix}/{package_manager}/{dependency}-{version}"
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80

生成例は次のとおりです。

deps-npm-and-yarn-lodash-4.17.21

templateとほかの書式設定を組み合わせた場合、処理は次の順番で行われます。

  1. テンプレート内のプレースホルダーを実際の値に置き換える
  2. /をseparatorで指定した文字へ置き換える
  3. _をword-separatorで指定した文字へ置き換える
  4. プレフィックス以降の大文字・小文字を変換する
  5. max-lengthに合わせて切り詰める

テンプレートに記述した/も、テンプレート展開後にseparatorの設定で置換されます。(GitHub Docs)

templateで使用できるプレースホルダー

使用できるプレースホルダーは、単独更新、同一エコシステムのグループ更新、マルチエコシステムグループで異なります。

プレースホルダー単独更新グループ更新マルチエコシステム内容
{prefix}○○○設定したプレフィックス
{package_manager}○○－npm_and_yarnなどのパッケージエコシステム識別子
{directory}○○－依存関係ファイルのディレクトリ
{target_branch}○○○設定されているターゲットブランチ
{dependency}○－－更新する依存関係名
{version}○－－更新後のバージョンまたは参照
{group_name}－○○Dependabotで設定したグループ名
{name}○○○更新方式に応じた依存関係名またはグループ名

単独更新とグループ更新の両方で同じテンプレートを使いたい場合は、{dependency}と{version}を直接指定するより、{name}を使う方が扱いやすくなります。

pull-request-branch-name:
  template: "{prefix}/{package_manager}/{name}"

単独更新では、{name}に依存関係名とバージョンが使われます。グループ更新ではグループ名が使われます。(GitHub Docs)

単独更新とグループ更新を共通形式にする例

version: 2

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

    pull-request-branch-name:
      prefix: "deps"
      template: "{prefix}/{package_manager}/{name}"
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80

    groups:
      frontend-deps:
        patterns:
          - "react*"
          - "next*"

生成されるブランチ名は、更新方法によって次のように変わります。

更新方法生成例
lodashの単独更新deps-npm-and-yarn-lodash-4.17.21
frontend-depsのグループ更新deps-npm-and-yarn-frontend-deps-xxxxxxxxxx

グループ更新では、一意性を保証するために10文字のダイジェストが自動的に追加されます。このダイジェストは無効化できません。CIの正規表現を作るときは、グループ名の後ろに英数字が付くことを前提にしてください。(GitHub Docs)

マルチエコシステムグループで設定する方法

DockerとTerraformなど、複数のパッケージエコシステムを1つのPRにまとめる場合は、multi-ecosystem-groups側にpull-request-branch-nameを設定します。

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"

    pull-request-branch-name:
      template: "{prefix}/infra/{name}"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80

updates:
  - package-ecosystem: "docker"
    directory: "/infra"
    patterns:
      - "nginx"
      - "redis"
    multi-ecosystem-group: "infrastructure"

  - package-ecosystem: "terraform"
    directory: "/infra"
    patterns:
      - "hashicorp/*"
    multi-ecosystem-group: "infrastructure"

生成されるブランチ名は、次のような形式になります。

dependabot/infra/infrastructure-xxxxxxxxxx

マルチエコシステムグループでは、単一のパッケージマネージャーを特定できないため、{package_manager}を利用できません。{directory}、{dependency}、{version}も使用できないため、{prefix}、{name}、{group_name}などで構成します。

また、マルチエコシステムグループに参加する個別のupdatesエントリへ、別々のpull-request-branch-nameを設定することはできません。グループ側の設定が使用されます。(GitHub Docs)

設定を導入する手順

現在のブランチ名依存処理を洗い出す

最初に、リポジトリと外部CIから次の文字列を検索します。

dependabot/
dependabot/**
startsWith(github.head_ref
GITHUB_HEAD_REF
pull_request.head.ref

確認対象は、GitHub Actionsだけではありません。

確認対象見落としやすい箇所
GitHub Actionsif条件、キャッシュキー、成果物名、Dockerタグ生成
外部CIブランチ許可リスト、正規表現、ジョブ振り分け条件
自動マージ処理dependabot/で始まるかを判定する処理
ブランチルール特定のブランチパターンに対する制限
デプロイスクリプトブランチ名から環境名やタグを作る処理
通知処理SlackやTeamsへの振り分け条件

必要最小限の設定から始める

CIが求める条件が「小文字、ハイフン区切り、80文字以内」だけなら、最初から複雑なtemplateを使う必要はありません。

pull-request-branch-name:
  separator: "-"
  word-separator: "-"
  branch-name-case: "lowercase"
  max-length: 80

プレフィックスや構造まで変更する必要が生じた段階で、prefixやtemplateを追加します。設定項目を増やしすぎると、グループ更新やマルチエコシステム更新で利用できないプレースホルダーを混ぜやすくなります。

CI側の条件も同じ変更で更新する

たとえば、変更前に次の条件を使っていたとします。

if: ${{ startsWith(github.head_ref, 'dependabot/') }}

プレフィックスをdeps、区切り文字をハイフンに変更するなら、次のように修正します。

if: ${{ startsWith(github.head_ref, 'deps-') }}

ただし、DependabotのPRかどうかを判定する目的だけなら、ブランチ名よりPR作成者を確認する方が、命名規則の変更に強くなります。

if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}

GitHub公式ドキュメントでも、Dependabotによる実行をdependabot[bot]で識別する例が示されています。(GitHub Docs)

次に作成される新しいPRで確認する

pull-request-branch-nameの変更は、すでに開いているDependabotのPRには反映されません。設定変更後に新しく作成されるPRだけが対象です。既存PRのブランチ名が変わらなくても、設定失敗とは限りません。(GitHub Docs)

確認時は、次の3種類を分けて確認すると安全です。

  1. 依存関係1件の単独更新
  2. groupsを使ったグループ更新
  3. multi-ecosystem-groupsを使った更新

特にグループ更新ではダイジェストが追加されるため、単独更新だけではCIの正規表現を十分に検証できません。

GitHub Actionsのbranches指定と混同しない

GitHub Actionsの次の設定は、Dependabotが作成するソースブランチを絞り込むものではありません。

on:
  pull_request:
    branches:
      - "main"

pull_request.branchesは、PRのマージ先となるターゲットブランチを指定します。上記は「mainを対象とするPR」でワークフローを実行する設定です。

DependabotのようなPRの作成元ブランチを条件にしたい場合は、github.head_refを使用します。

jobs:
  check-dependabot-branch:
    if: ${{ startsWith(github.head_ref, 'deps-') }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Dependabot branch detected"

ブランチ名変更後にGitHub Actionsが動かなくなった場合、on.pull_request.branchesを直すのではなく、github.head_ref、github.event.pull_request.head.ref、シェルスクリプト内の正規表現を確認してください。(GitHub Docs)

セキュリティ更新への適用範囲

pull-request-branch-nameは、Dependabotのバージョン更新だけでなく、同じパッケージエコシステムのセキュリティ更新にも適用されます。

ただし、target-branchで既定ブランチ以外を指定している場合、そのupdatesエントリの設定はバージョン更新だけに適用されます。Dependabotのセキュリティ更新は既定ブランチを対象に作成されるためです。(GitHub Docs)

たとえば、次の設定ではdevelop向けのバージョン更新にカスタムブランチ名が使われますが、既定ブランチ向けのセキュリティ更新には同じ設定が適用されません。

version: 2

updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    target-branch: "develop"

    pull-request-branch-name:
      prefix: "deps"
      separator: "-"
      branch-name-case: "lowercase"

template設定で使用できない文字

templateから生成される名前は、有効なGit参照名でなければなりません。次のような文字を含むテンプレートは検証エラーの原因になります。

スペース
~
^
:
?
*
[
\

..や@{といった文字列の並びも拒否されます。テンプレート内に説明用の空白やコロンを入れないようにしてください。(GitHub Docs)

安全なテンプレートは、英数字、ハイフン、アンダースコア、スラッシュを中心に構成します。

template: "{prefix}/{package_manager}/{name}"

次のように空白を含める形式は避けます。

template: "{prefix} / {package_manager} / {name}"

よくある失敗と対処方法

症状主な原因対処
設定後も既存PRの名前が変わらない既存PRは変更対象外次に新規作成されるPRで確認する
YAMLエラーになるseparator: -と記述しているseparator: "-"のように引用符で囲む
/は消えたが_が残るseparatorしか設定していないword-separator: "-"を追加する
lowercaseを指定してもプレフィックスが大文字プレフィックスは変換対象外prefix自体を小文字で記述する
グループ更新の末尾に英数字が付く一意性確保用のダイジェスト正規表現で10文字のダイジェストを許可する
マルチエコシステムの設定が検証エラーになる{package_manager}などを使用している{prefix}、{name}、{group_name}などに変更する
PRタイトルが変わらない今回の設定はブランチ名専用PRタイトルはcommit-messageで設定する
GitHub Actionsが実行されないgithub.head_refの条件が旧形式のまま新しいプレフィックスと区切り文字へ更新する
ブランチ名が途中で切れるmax-lengthを超えている上限を調整するか、templateから不要な要素を外す

pull-request-branch-nameはPRのブランチ名を変更する設定であり、コミットメッセージやPRタイトルを変更するものではありません。PRタイトルのプレフィックスを変更したい場合は、別のcommit-message設定を使用します。(GitHub Docs)

Dependabotのブランチ名を変更するときの判断基準

設定項目は多いものの、すべて指定する必要はありません。実務では、次の基準で選ぶと過剰な設定を避けられます。

要件推奨設定
/だけが問題separator
/と_の両方が問題separatorとword-separator
大文字を禁止したいbranch-name-case: "lowercase"
外部サービスに文字数制限があるmax-length
社内の命名規則で先頭が決まっているprefix
要素の順番を変更したいtemplate
単独更新とグループ更新を共通化したい{name}を使ったtemplate
複数エコシステムをまとめているmulti-ecosystem-groups側で設定

特別な理由がなければ、次の設定から始めるのが扱いやすい構成です。

pull-request-branch-name:
  separator: "-"
  word-separator: "-"
  branch-name-case: "lowercase"
  max-length: 80

そのうえで、ブランチ名から更新元を判別したい場合はprefixを追加し、構造まで制御する必要がある場合だけtemplateを追加します。

設定前には、既存のdependabot/を前提にしたCI条件を検索してください。設定後は、既存PRではなく新しく作成されたPRで確認し、単独更新だけでなくグループ更新のダイジェストまで含めてテストすることが重要です。

WEBサービス
GitHub CI/CD Dependabot dependabot.yml

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次