【修正版】Bitbucket アプリパスワード廃止と Gitcola での API トークン移行

【重要】この記事は過去の調査結果と実際の試行を通じて得られた知見を基に修正されています。

特に、Bitbucket の API トークンを利用した Git 認証の際にうまくいかないことが判明しました。実際に動作確認が取れた方法で再解説しています。

はじめに

Git を使った開発において、リモートリポジトリとの認証は開発ワークフローの根幹を成す部分です。開発プラットフォームである Bitbucket がアプリパスワードの廃止を決定し、今後はよりセキュアな API トークンへの移行を必須とするという通知がありました。

私は長らく ChromeOS Flex の Linux 開発環境で Gitcola を Git クライアントとして利用しており、Bitbucket のプライベートリポジトリとの認証にはアプリパスワードを使用してきました。

Gitcola 公式サイト

これまで大きな問題なく利用できていましたが、最近になってプッシュ時に以下の警告メッセージが表示されるようになり、将来的な開発ワークフローへの影響が懸念されました。

2025-06-23 16:04:26:  "git push" は終了ステータスとして 0 を返しました。
2025-06-23 16:04:26:  
2025-06-23 16:04:26:  Pushing to https://bitbucket.org/your_workspace/your_repository.bitbucket.io.git
2025-06-23 16:04:26:  POST git-receive-pack (chunked)
2025-06-23 16:04:26:  remote: 
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mYou are using an app password for Git over HTTPS.[38;5;226;48;5;232m        
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mOn September 9, 2025, the creation of app passwords will be discontinued.[38;5;226;48;5;232m        
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mFrom that date forward, you will need to create and use API tokens.[38;5;226;48;5;232m        
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mAll existing app passwords will become inactive on June 9, 2026.[38;5;226;48;5;232m        
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mMore details:[38;5;226;48;5;232m        
2025-06-23 16:04:26:  remote: [38;5;226;48;5;232mhttps://support.atlassian.com/bitbucket-cloud/docs/api-tokens/[0m        
2025-06-23 16:04:26:  To https://bitbucket.org/your_workspace/your_repository.bitbucket.io.git
2025-06-23 16:04:26:     142397e..588d1b3  master -> master
2025-06-23 16:04:26:  updating local tracking ref 'refs/remotes/origin/master'
2025-06-23 16:04:26:  

本記事は、この Bitbucket の認証方法変更に対する私の調査結果と実際の移行経験をまとめたものです。Gitcola が API トークンに対応しているか、どのように移行すべきか、そしてその際の懸念点と解決策について、Gitcola 開発者や Bitbucket の公式情報、そして自身の検証を通じて得られた知見を共有します。同じ状況に直面している方の参考になれば幸いです。

---

1. Bitbucket のアプリパスワード廃止と API トークン移行の背景

まず、今回の認証方法変更の概要と背景を確認することは不可欠です。なぜ Bitbucket がこのような変更を決定したのかを理解することで、今後の対応の重要性がより明確になります。

1.1. 迫り来るアプリパスワードの廃止スケジュール

Bitbucket から表示される警告メッセージ（前述の「はじめに」の出力参照）によると、アプリパスワードは以下のスケジュールで段階的に廃止されます。

• 2025年9月9日以降: 新しいアプリパスワードの作成が不可能になります。
  • この日付を過ぎると、新たなアプリケーションや環境でアプリパスワードを使おうとしても、それ自体を生成することができなくなります。
• 2026年6月9日以降: 既存のすべてのアプリパスワードが完全に無効化されます。
  • この日付を過ぎると、現在使用しているアプリパスワードは一切利用できなくなり、Bitbucket への認証が突然失敗するようになります。

つまり、私が利用しているアプリパスワードは、2026年6月9日には確実に利用できなくなります。それまでに、Git や Gitcola が Bitbucket との認証に利用する仕組みを、アプリパスワードから API トークンへと切り替える作業を完了させる必要があります。

1.2. API トークンへの移行理由：セキュリティの強化

Bitbucket がアプリパスワードを廃止し、API トークンへの移行を促す最も重要な理由は、セキュリティの強化にあります。Bitbucket Supportのチャットボットとのやり取りからも、その背景が詳しく説明されています。

チャットボットからの回答：

Atlassian is moving away from app passwords and encouraging the use of API tokens for authentication because API tokens offer improved security. App passwords and tokens that never expire can pose a data security risk if they are lost or compromised. By requiring API tokens to have an expiration date (from 1 to 365 days), Atlassian helps ensure that access is regularly reviewed and reduces the risk of unauthorized long-term access.

この説明が示す通り、API トークンが提供する主要なセキュリティ上のメリットは以下の2点です。

• 有効期限の設定（必須）:
  • API トークンは、生成時に必ず有効期限（最短1日～最長1年）を設定する必要があります。これにより、たとえトークンが外部に漏洩してしまったとしても、その漏洩したトークンが不正に利用される期間を限定できます。無期限で利用できるアプリパスワードは、一度漏洩すると永久的なセキュリティリスクとなり得たため、この点は大きな改善ですませす。
  • チャットボットによると、「2024年12月15日以降に作成される新しいAPIトークンは、デフォルトで1年の有効期限が設定される」とのことです。
• スコープ（権限）の限定:
  • API トークンは、特定の操作（例: リポジトリの読み書きのみ、パイプラインの実行のみなど）に限定された権限（スコープ）を付与して生成できます。これにより、万が一トークンが不正利用された場合でも、そのトークンで可能な操作が最小限に抑えられ、被害範囲を限定することができます。
  • チャットボットからも「Create API token with scopesは、何ができるか正確に指定できるよりセキュアな方法」「Create API tokenは互換性のためで、Broadなアクセス」と説明されており、With Scopesでの作成が強く推奨されています。

毎年、認証情報の更新という手間は発生しますが、これは Bitbucket での決定事項なので対応せざるを得ないということです。

---

2. Gitcola は Bitbucket の API トークンに対応しているのか？の調査

私が最も懸念していたのは、長年使用してきた Gitcola が Bitbucket の新しい認証方法に対応できるのか、という点でした。もし対応できないとなると、新たな Git クライアントを探す必要が生じ、これまでのワークフローが大きく変わってしまう可能性があります。

この疑問を解消するため、私は Gitcola の Issue に直接質問を投稿し、開発者さんからの回答をもらいました。

2.1. Gitcola 開発者 David Aguilar 氏からの回答

Gitcola のメインメンテナーである David Aguilar 氏 (@davvid) から、非常に迅速かつ明確な回答が得られました。彼のプロフィールページ にも、彼が Gitcola の主要な開発者であることが明記されており、その回答の信頼性は非常に高いと言えます。

私が投稿した質問内容：

Hello,
I've been using Gitcola for about a year now in my ChromeOS Flex Linux development environment, and it's been a great tool.
My remote repositories are private and hosted on Bitbucket. Up until recently, I've been successfully pushing my changes by entering an app password when prompted by Gitcola.
However, during my recent push attempts, I've started receiving a warning message from Bitbucket indicating that app passwords will be deprecated and that I should switch to using API tokens instead.
Could you please confirm if Gitcola currently supports Bitbucket's API tokens for authentication? If it does, could you kindly provide instructions on how to set it up? If not, are there any recommended alternative approaches for users like me to continue using Gitcola with Bitbucket, or should I consider a different Git client altogether?
Thank you for your time and assistance.

これに対する David 氏からの回答（抜粋）：

davvid commented:
It should work fine. As long as git push and git pull work, cola will also work because it uses those same commands under the hood.
I suspect you're looking for these instructions:
https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/
cheers

davvid commented:
If you want to continue entering something into a password prompt, i.e. the API token in the new approach, look for the, "For repositories already cloned to the local device, update the remote URL with the following command:" step.
You'll have to do that to update an existing (previously cloned) repo so that you can use API tokens with it.

この回答から、以下の事実が判明しました。

• Gitcola は Git コマンドのラッパーである:
  • David 氏の回答の核心は、「git push と git pull が機能する限り、cola も機能します。なぜなら、cola は内部で同じコマンドを使っているからです」という点にあります。これは、Gitcola が認証システムを独自に持っているわけではなく、Linux 環境にインストールされている標準の Git コマンド（Git CLI）を呼び出し、その結果を GUI で表示しているという Gitcola の基本的な動作原理を示しています。
• Git CLI が機能すれば Gitcola も機能する:
  • したがって、Gitcola 自体が API トークンを「サポートする」というよりは、Git のコマンドラインインターフェース（CLI）で API トークンを使った認証が成功する状態であれば、Gitcola もその恩恵を受けて問題なく動作するということです。Gitcola 側での特別な「API トークン対応」のアップデートや、固有の設定は不要であると判断できます。
• Bitbucket 側の設定（およびローカル Git の設定）が必要:
  • David 氏が Bitbucket の公式ドキュメントへのリンク（https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/）を提示していることからも、問題は Gitcola ではなく、Git そのものが Bitbucket の API トークンを認識し、利用できるように設定することにあると明確に示されています。

この調査結果により、Gitcola の継続利用に希望が見えました。Bitbucket の API トークン移行に伴い Gitcola の利用を諦める必要はなく、ローカルの Git 環境で API トークンを設定すれば良いということが分かりました。

2.2. アプリパスワード廃止後の Gitcola の挙動（再確認）

Bitbucket のチャットボットとのやり取りからも、この点についての情報が得られました。

私の質問：

app passwordsを使用していたのでレガシィアプリケーションだと思いますが、"Create API token"でAPIを生成すれば有効期限はありませんか？

チャットボットからの回答（抜粋）：

「Create API token」でAPIトークンを生成した場合でも、無期限（有効期限なし）のトークンは作成できません。
現在、APIトークンの有効期限は「1日～1年（365日）」の範囲で設定する必要があります。
また、2024年12月15日以降に作成される新しいAPIトークンは、デフォルトで1年の有効期限が設定されます。
2024年12月15日以前に作成されたトークンも、2025年3月14日～5月12日の間に有効期限が設定され、順次失効します。
まとめ
「Create API token」で作成したAPIトークンも有効期限（1～365日）が必須です。
無期限のAPIトークンは作成できません。
セキュリティ強化のための仕様変更です。

この情報と、最初にGitcolaから得られた警告メッセージを総合すると、私が現在使用しているアプリパスワードは2026年6月9日までは機能し続けます。しかし、それ以降は無効化されるため、必ずそれまでに API トークンへの移行を完了させる必要があります。API トークンを新しく作成しても、既存のアプリパスワードが直ちに無効になるわけではないため、焦らず移行作業を進めることができます。

---

3. API トークン移行の作業手順（実証済み）

Gitcola 開発者の回答と Bitbucket の公式情報を踏まえ、API トークンを利用して Git 認証を行う具体的な手順を、実際に試行し、成功した方法で詳細に解説します。

3.1. 【作業開始前】 ローカルリポジトリの事前バックアップ（必須！）

新しい認証方法への切り替え作業は、Git の設定を変更する性質上、万が一の失敗への備えが非常に重要です。誤ったコマンド実行や設定ミスにより、現在の Git 環境が一時的に利用できなくなる可能性はゼロではありません。そのため、作業を行う前に、現在のローカルリポジトリのフォルダを丸ごと別の場所にコピーし、完全なバックアップを取っておくことを強く推奨します。

• 手順例（ChromeOS Flex の Linux 環境の場合）：

  1. ファイルマネージャー（Files アプリなど）を開き、Linux ファイルシステムにアクセスします。
  2. 現在作業しているローカルリポジトリのフォルダ（例: /home/your_user_name/my-projects/your_repository_name）を見つけます。
  3. このフォルダを丸ごとコピーします（Ctrl+C）。
  4. コピー先の安全な場所（例: /home/your_user_name/Documents/Git_Backups/your_repository_name_20250709_backup など）に貼り付けます（Ctrl+V）。日付などを付けておくと、複数のバックアップを作成した場合に管理しやすくなります。

• もし問題が発生した場合の復元方法：
  万が一、以降の手順で Git の認証がうまくいかない、あるいは予期せぬ問題が発生した場合でも、このバックアップがあれば安心です。

  1. 問題が発生している現在のローカルリポジトリのフォルダ（例: /home/your_user_name/my-projects/your_repository_name）を完全に削除します。
  2. バックアップしたフォルダ（例: /home/your_user_name/Documents/Git_Backups/your_repository_name_20250709_backup）を、元のローカルリポジトリがあった場所（例: /home/your_user_name/my-projects/）にコピーし、元のフォルダ名（例: your_repository_name）にリネームして戻します。
     これで、git remote set-url を実行する前の状態に安全に復旧し、別の解決策を検討したり、再度手順を見直したりする時間を確保できます。

3.2. 【手順1】 Bitbucket 上で API トークンを生成する

Git リポジトリへのアクセスを許可する API トークンを Bitbucket のウェブインターフェースで生成します。

1. Bitbucket にログインします。
   お使いのウェブブラウザで Bitbucket にアクセスし、ご自身の ID とパスワードでログインしてください。

2. 個人設定画面へ移動します。
   通常、Bitbucket の画面右上にある歯車のアイコンをクリックし、ドロップダウンメニューから [Personal settings] の中の [Atlassian account settings] をクリックします。

3. API トークンの管理セクションへ移動します。
   設定画面の上側のナビゲーションメニューから、[セキュリティ] タブをクリックして、[API トークンの作成と管理] を探してクリックします。

4. 新しい API トークンの作成を開始します。
   API トークンの一覧が表示される画面で、[API トークンを作成] または [スコープ付き API トークンを作成] ボタンをクリックします。

   • 重要： ここでは「スコープ付き API トークンを作成」 を選択することを強く推奨します。チャットボットの回答にもあった通り、スコープ付きトークンはセキュリティが高く、必要な権限のみを付与できるためです。「API トークンを作成」（スコープなし）はレガシー互換性のためであり、通常は選択すべきではありません。

5. トークンの詳細を設定します。

   • 名前 (Label): 後で識別しやすいように、任意の名前を付けます。用途がわかるような名前にすると良いでしょう。

   • 有効期限 (Expires on): ドロップダウンメニューから、有効期限を選択します。最長である1年後の日付を選択することをお勧めします。有効期限が短すぎると、頻繁に更新作業が必要になり、手間が増えてしまいます。

   • パーミッション（スコープ）の選択:
     Git の基本的な操作（プッシュ、プル、クローンなど）を行うために必要なパーミッションを選択します。私は個人開発者としてリポジトリのオーナーであり、全ての権限を有しているので、以下の「Repositories」に関するパーミッションを付与しました。これにより、Git の操作だけでなく、将来的なリポジトリ管理（例: ブランチルールの変更など）もこのトークンで可能になります。

     • Repositories:
       • Read: リポジトリのコードやデータの表示、ファイルブラウジング、プル操作に必要です。(read:repository:bitbucket)
       • Write: ソースコードの変更（コミットのプッシュ）を可能にします。プッシュ操作には不可欠です。(write:repository:bitbucket)
       • Admin: リポジトリの管理活動（例: ブランチ制限の設定、ブランチモデルの編集など）を許可します。オーナーであれば持っておくべきです。(admin:repository:bitbucket)
       • Delete: リポジトリの削除を許可します。オーナーとして完全な管理を行う場合に付与します。(delete:repository:bitbucket)

     注: ここで挙げた以外の「Pull requests」「Pipelines」「Issues」などのパーミッションは、Git の基本的なコード管理機能とは直接関係なく、Bitbucket の付加機能（例: CI/CD、課題管理）を API 経由で操作する際に必要となるものです。Gitcola で通常の Git 操作を行うだけであれば、これらのパーミッションは不要です。セキュリティの観点からは、必要最小限の権限を付与することがベストプラクティスですが、個人リポジトリのオーナーであれば上記「Repositories」の全権限で問題ないでしょう。

6. トークンを生成し、文字列をコピーします。
   設定が完了したら、[Create] ボタンをクリックしてトークンを生成します。
   重要： 生成されると、一度だけトークン文字列が画面に表示されます。この文字列は非常に重要なので、表示されたらすぐに安全な場所にコピーして保存してください。 一度この画面を閉じると、このトークン文字列を再表示することはできません。もしコピーし忘れた場合は、そのトークンを削除して新しいトークンを生成し直す必要があります。

3.3. 【手順2】 ローカルリポジトリのリモート URL を API トークンで更新する（成功例）

Bitbucket で生成した API トークンを、Git が利用できるようにローカルリポジトリのリモート URL を更新します。Gitcola は内部でこの設定を利用します。

この方法は、HTTPS 形式のリモート URL の中に、Bitbucket のユーザー名と API トークンを埋め込む形式になります。

1. 対象のローカルリポジトリのディレクトリに移動します。
   ターミナル（ChromeOS Flex の Linux 環境）を開き、API トークン認証に切り替えたい Git リポジトリのルートディレクトリに移動します。

   cd /path/to/your/local/repository
   # 例: cd ~/my-projects/your_repository_name
   

2. 現在設定されているリモート URL を確認します。
   念のため、現在のリモート URL の設定を確認します。

   git remote -v
   

   実行すると、以下のような出力が得られるはずです。

   origin  https://bitbucket.org/your_workspace/your_repository_name.bitbucket.io.git (fetch)
   origin  https://bitbucket.org/your_workspace/your_repository_name.bitbucket.io.git (push)
   

   これは、現在のリモート「origin」が https:// で始まる Bitbucket の URL を指していることを示しています。

3. git remote set-url コマンドを使用して、リモート URL を更新します。
   Bitbucket のユーザー名と API トークンを埋め込んだ URL に更新するコマンドを実行します。

   git remote set-url origin https://your_bitbucket_username:[e-mail]/your_workspace/your_repository_name.bitbucket.io.git
   

   • your_bitbucket_username の部分は、あなたのBitbucket ユーザー名に置き換えてください。
   • your_workspace の部分は、あなたのworkspace名に置き換えてください。
   • YOUR_API_TOKEN の部分を、先ほど Bitbucket で生成し、安全な場所に保存した実際の API トークン文字列に置き換えてください。
   • your_repository_name の部分は、あなたのリポジトリ名に置き換えてください。

   例：
   もし Bitbucket ユーザー名が mydevid で、workspace名がwkdevid で、リポジトリ名が my-awesome-app.bitbucket.io、生成した API トークンが ATBBABCD1234567890EFGH であった場合：

   git remote set-url origin https://mydevid:[e-mail]/wkdevid/my-awesome-app.bitbucket.io.git
   

   このコマンドを実行しても、通常は何も出力されませんが、内部でリモート URL の設定が更新されています。

   ---

   【補足】以前試して失敗した形式について

   以前の調査で、x-token-auth をユーザー名とする以下の形式を試しましたが、私の環境では認証に失敗しました。

   # この形式では私の環境では認証に失敗しました
   git remote set-url origin https://x-token-auth:[e-mail]/your_workspace/your_repository_name.bitbucket.io.git
   

   ---

4. リモート URL が更新されたことを確認します。
   再度 git remote -v コマンドを実行して、URL が正しく更新されたことを確認してください。

   git remote -v
   

   出力が以下のような形式になっていれば成功です。

   origin  https://your_bitbucket_username:[e-mail]/your_workspace/your_repository_name.bitbucket.io.git (fetch)
   origin  https://your_bitbucket_username:[e-mail]/your_workspace/your_repository_name.bitbucket.io.git (push)
   

   これで、ローカルの Git 環境（および Gitcola）は、Bitbucket との通信に新しい API トークンを使用するよう設定されました。

3.4. 【手順3】 認証テストの実施

設定が正しく機能するかどうかを確認します。

1. Gitcola からプッシュを試す。
   Gitcola を開き、何か簡単な変更（例えば README.md に一行追加など）を行い、コミットしてプッシュを試みてください。
   または、ターミナルから直接 git push を試しても構いません。

   git push origin master # もしくは現在のブランチ名
   

   アプリパスワードを要求するプロンプトが表示されず、プッシュが正常に完了すれば成功です。

---

4. 移行における運用上の考慮点

API トークンへの移行が完了した後も、継続的な開発ワークフローを維持するために考慮すべき運用上の懸念点についてまとめました。

4.1. 有効期限による定期的な更新の手間

API トークンには最大1年の有効期限があるため、継続して開発を行う場合は、定期的に新しいトークンを生成し、リモート URL を更新する作業が必要になります。これは、無期限だったアプリパスワードと比較すると、新たな運用上の手間となります。

• 解決策：リマインダーの設定と計画的な更新
  • API トークンを生成した際に、その有効期限をカレンダーアプリやタスク管理ツールに登録し、期限が来る数週間～1ヶ月前には通知が来るように設定します。これにより、有効期限切れによる突然の認証エラーを防ぎ、余裕を持って計画的に更新作業を行うことができます。
  • 更新作業自体は、「3. API トークン移行の作業手順（実証済み）」の「3.2. 【手順1】 Bitbucket 上で API トークンを生成する」と「3.3. 【手順2】 ローカルリポジトリのリモート URL を API トークンで更新する（成功例）」を再度行うだけです。

4.2. 既存のローカルリポジトリへの影響

git remote set-url コマンドで URL を更新した場合、現在利用しているローカルリポジトリのファイルやコミット履歴に何らかの悪影響がないか、あるいはリポジトリを一度削除して再クローンし直す必要があるのではないか、という懸念がありました。

• 解決策：ローカルリポジトリの削除は不要、既存のまま利用可能
  • この懸念については、調査の結果、全く問題ないことが分かりました。git remote set-url コマンドは、リポジトリ内の .git/config ファイルに記述されているリモート設定（どの URL をリモートの「origin」として認識するか、など）のみを変更します。ローカルのファイルやコミット履歴、ブランチの状態など、他のリポジトリの内容には一切影響を与えません。
  • したがって、現在利用しているローカルリポジトリを削除したり、再度クローンし直したりする必要は一切ありません。 安心して、既存のローカルリポジトリをそのまま使用し続けることができます。

---

5. まとめと今後の展望

今回の綿密な調査と実際の試行を通じて、Bitbucket のアプリパスワード廃止は確実であり、API トークンへの移行が開発ワークフローを維持するために不可欠であることが改めて確認されました。同時に、私が使用する Gitcola がこの変更に問題なく対応できることも明確になり、大きな安心感を得られました。

最も重要な発見は、Gitcola 自体が API トークン認証を「サポート」するというよりは、基盤となる Git コマンドラインレベルで API トークンが正しく機能するように設定すれば良いという点です。また、API トークンを URL に含める際の形式として、https://{your_bitbucket_username}:{api_token}@bitbucket.org/{your_workspace}/{your_repository_name}.bitbucket.io.git の形式が確実に機能することが実証されました。

具体的な移行手順は、Bitbucket で API トークンを生成し、そのトークンを使ってローカルリポジトリの git remote set-url を更新するという比較的シンプルなものです。有効期限の管理という新たな手間は発生しますが、リマインダーの活用や、万全を期すための事前バックアップといった対策を講じることで、安全かつスムーズな移行が可能です。

2025年9月9日の新規アプリパスワード作成停止、そして2026年6月9日の既存アプリパスワード無効化という期限が迫っています。この情報が、Bitbucket のアプリパスワード廃止に直面し、Gitcola など既存の Git クライアントでの継続利用に不安を感じている方々の一助となり、スムーズな移行の道筋を示すことができれば幸いです。

---