【警告】
この記事はあくまで調査結果のまとめであり、誤りがあります。実際試した修正版があります。

注意事項
この記事はあくまで調査結果のまとめです。まだ実際に試していないのでご注意ください。

はじめに

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

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

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

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_user_id/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_user_id/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.3. アプリパスワード廃止後の 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. Bitbucket API トークンを利用した Git 認証の具体的な手順（調査結果）

Gitcola 開発者の回答と Bitbucket の公式情報を踏まえ、API トークンを利用して Git 認証を行う具体的な手順を、実際に作業を行う際のイメージを想定して詳細に調査・整理しました。

3.1. 【ステップ1】 Bitbucket 上で API トークンを生成する

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

Bitbucket にログインします。
お使いのウェブブラウザで Bitbucket にアクセスし、ご自身の ID とパスワードでログインしてください。
個人設定画面へ移動します。
通常、Bitbucket の画面右上にある**歯車のアイコン**をクリックし、ドロップダウンメニューから [Personal settings] の中の　[Atlassian account setting] をクリックします。
API トークンの管理セクションへ移動します。
設定画面の上側のナビゲーションメニューから、[セキュリティ] タブをクリックして、 [API トークンの作成と管理] を探してクリックします。
新しい API トークンの作成を開始します。
API トークンの一覧が表示される画面で、[API トークンを作成] または [スコープ付き API トークンを作成] ボタンをクリックします。
- 重要： ここでは**「スコープ付き API トークンを作成」** を選択するほうが良さそうです。チャットボットの回答にもあった通り、スコープ付きトークンはセキュリティが高く、将来的な標準となります。「API トークンを作成」（スコープなし）はレガシー互換性のためであり、通常は選択すべきではありません。
トークンの詳細を設定します。
- 名前 (Label): 後で識別しやすいように、任意の名前を付けます。例えば、gitcola_my_repo_access や chromeos_flex_git など、用途がわかるような名前にすると良いでしょう。
- 有効期限 (Expires on): ドロップダウンメニューから、有効期限を選択します。最長である「1 year (365 days)」を選択することをお勧めします。有効期限が短すぎると、頻繁に更新作業が必要になり、手間が増えてしまいます。
- パーミッション（スコープ）の選択:
  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」の全権限で問題ないでしょう。
トークンを生成し、文字列をコピーします。
設定が完了したら、[Create] ボタンをクリックしてトークンを生成します。
重要： 生成されると、一度だけトークン文字列が画面に表示されます。この文字列は非常に重要なので、表示されたらすぐに安全な場所にコピーして保存してください。 一度この画面を閉じると、このトークン文字列を再表示することはできません。もしコピーし忘れた場合は、そのトークンを削除して新しいトークンを生成し直す必要があります。

3.2. 【ステップ2】ローカルリポジトリのリモート URL を API トークンで更新する

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

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

対象のローカルリポジトリのディレクトリに移動します。
ターミナル（ChromeOS Flex の Linux 環境）を開き、API トークン認証に切り替えたい Git リポジトリのルートディレクトリに移動します。
```
cd /path/to/your/local/repository
# 例: cd ~/my-projects/your_repository
```
現在設定されているリモート URL を確認します。
念のため、現在のリモート URL の設定を確認します。
```
git remote -v
```
実行すると、以下のような出力が得られるはずです。
```
origin  https://bitbucket.org/your_user_id/your_repository.bitbucket.io.git (fetch)
origin  https://bitbucket.org/your_user_id/your_repository.bitbucket.io.git (push)
```
これは、現在のリモート「origin」が https:// で始まる Bitbucket の URL を指していることを示しています。
git remote set-url コマンドを使用して、リモート URL を更新します。
いよいよ、新しい API トークンを埋め込んだ URL に更新するコマンドを実行します。Bitbucket の場合、ユーザー名として x-token-auth という固定の文字列を使用し、パスワードの代わりに API トークンを記述します。
```
git remote set-url origin https://x-token-auth:YOUR_API_TOKEN@bitbucket.org/your_user_id/your_repository.bitbucket.io.git
```
- YOUR_API_TOKEN の部分を、先ほど Bitbucket で生成し、安全な場所に保存した実際の API トークン文字列に置き換えてください。
- your_user_id と your_repository の部分は、ご自身のBitbucket IDとリポジトリ名に置き換えてください。
例：
もし Bitbucket ID が mydevid で、リポジトリ名が my-awesome-app.bitbucket.io、生成した API トークンが ATBBABCD1234567890EFGH であった場合：
```
git remote set-url origin https://x-token-auth:ATBBABCD1234567890EFGH@bitbucket.org/mydevid/my-awesome-app.bitbucket.io.git
```
このコマンドを実行しても、通常は何も出力されませんが、内部でリモート URL の設定が更新されています。
リモート URL が更新されたことを確認します。
再度 git remote -v コマンドを実行して、URL が正しく更新されたことを確認してください。
```
git remote -v
```
出力が以下のような形式になっていれば成功です。
```
origin  https://x-token-auth:YOUR_API_TOKEN@bitbucket.org/your_user_id/your_repository.bitbucket.io.git (fetch)
origin  https://x-token-auth:YOUR_API_TOKEN@bitbucket.org/your_user_id/your_repository.bitbucket.io.git (push)
```
これで、ローカルの Git 環境（および Gitcola）は、Bitbucket との通信に新しい API トークンを使用するよう設定されました。

3.3. 【ステップ3】認証テストの実施

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

Gitcola からプッシュを試す。
Gitcola を開き、何か簡単な変更（例えば README.md に一行追加など）を行い、コミットしてプッシュを試みてください。
または、ターミナルから直接 git push を試しても構いません。
```
git push origin master # もしくは現在のブランチ名
```
アプリパスワードを要求するプロンプトが表示されず、プッシュが正常に完了すれば成功です。

4. 移行における懸念点と解決策（調査結果）

API トークンへの移行に際して考えられる懸念点と、その解決策について詳細に調査し、まとめてみました。

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

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

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

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

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

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

4.3. 作業中の万が一の失敗への備え

新しい認証方法への切り替え作業中、誤ったコマンド実行や設定ミスにより、現在のGit環境が利用できなくなってしまうのではないかという心配がありました。特に、まだ未実施の作業のため、不安は拭えません。

解決策：ローカルリポジトリの事前バックアップ（最も推奨される安全策）
- この懸念に対する最もシンプルかつ効果的な安全策は、作業を行う前に、現在のローカルリポジトリのフォルダを丸ごと別の場所にコピーし、完全なバックアップを取っておくことです。
- 手順例（ChromeOS Flex の Linux 環境の場合）：
  1. ファイルマネージャー（Files アプリなど）を開き、Linux ファイルシステムにアクセスします。
  2. 現在作業しているローカルリポジトリのフォルダ（例: /home/your_user_name/my-projects/your_repository）を見つけます。
  3. このフォルダを丸ごとコピーします（Ctrl+C）。
  4. コピー先の安全な場所に貼り付けます（Ctrl+V）。日付などを付けておくと、複数のバックアップを作成した場合に管理しやすくなります。
- 万が一、git remote set-url の実行後にプッシュができない、認証エラーが解決しないなど、予期せぬ問題が発生した場合でも、このバックアップがあれば安心です。
  - 問題が発生している現在のローカルリポジトリのフォルダを完全に削除します。
  - バックアップしたフォルダを、元のローカルリポジトリがあった場所（例: /home/your_user_name/my-projects/）にコピーし、元のフォルダ名（例: your_repository）にリネームして戻します。
- これにより、git remote set-url を実行する前の状態に安全に復旧し、別の解決策を検討したり、再度手順を見直したりする時間を確保できます。

5. まとめと今後の展望

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

重要な発見は、Gitcola 自体が API トークン認証を「サポート」するというよりは、基盤となる Git コマンドラインレベルで API トークンが正しく機能するように設定すれば良いという点です。

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

2025年9月9日の新規アプリパスワード作成停止、そして2026年6月9日の既存アプリパスワード無効化という期限が迫っています。私はこの調査結果に基づいて、これらの期日までに API トークンへの移行作業を実施する予定です。