Bitbucket地獄からの脱出：認証エラーを秒で解決し、開発速度を極限まで高める「プロの流儀」
現場で最も無駄な時間、それは「Gitが繋がらない」というエラー画面を眺めている時間だ。
Bitbucketを使っているチームで頻発する認証トラブルは、単なる設定ミスではない。多くの場合、「仕組みへの理解不足」と「認証情報の管理コスト」が開発スピードを殺していることに起因する。
今日は、トラブルシューティングの決定版として、認証エラーを撲滅する診断フローと、DevOpsのプロとして現場に導入すべき「爆速開発のためのベストプラクティス」を伝授する。
—
1. 【診断フローチャート】なぜ「Permission Denied」が出るのか？
SSH/HTTPS接続で詰まったら、まずは以下の優先順位で原因を切り分ける。迷っている時間は1秒もいらない。
Step 1: 接続プロトコルの確認
`git remote -v` を叩け。`https://` で始まっているか？ `git@bitbucket.org:` で始まっているか？
- HTTPSの場合: OSの認証情報マネージャー（Keychain/Credential Helper）に古いパスワードが残っているのが9割。
- SSHの場合: 公開鍵の登録先が「個人アカウント」か「ワークスペースのデプロイキー」かを確認。
Step 2: SSH接続テスト（最強のデバッグコマンド）
以下のコマンドを打てば、どこで詰まっているか一発でわかる。
-vT オプションで詳細なログを吐き出す
ssh -vT git@bitbucket.org
- `Permission denied (publickey)`: ローカルの秘密鍵が使われていない、あるいはBitbucket側に登録されていない。
- `Connection timed out`: 会社のプロキシやファイアウォールでポート22が塞がれている。この場合はHTTPSに切り替えるか、`~/.ssh/config` でポート443を試せ。
Step 3: SSHConfigの最適化
開発環境ごとに接続先を混同しているなら、`~/.ssh/config` をこう書け。これがプロの標準だ。
~/.ssh/config
Host bitbucket.org
HostName bitbucket.org
User git
IdentityFile ~/.ssh/id_ed25519_work # 鍵を明示的に指定
IdentitiesOnly yes # 余計な鍵を試さない（重要）
—
2. 開発スピードを「物理的」に底上げするハック
認証エラーを解決したら、次は「認証作業自体を消滅」させる。
① 認証情報の管理は「自動化」せよ
HTTPS派なら、OSの認証情報をリセットし、`git config –global credential.helper osxkeychain` (macOSの場合) を設定した上で、App Passwordを使え。個人のログインパスワードをGitに持たせるのは20世紀の遺物だ。
② 隠れたキーボードショートカット
Bitbucketの画面上でマウスを触るな。以下のショートカットを叩け。
- `?`: 全ショートカットを表示（まずはこれを覚えろ）
- `g` + `p`: Pull Request一覧へ飛ぶ
- `g` + `c`: コミット履歴へ飛ぶ
- `s`: 検索窓にフォーカス
—
3. チーム開発の「神」ルール：設定の共有化
設定ファイルが属人化しているチームは滅びる。プロジェクトルートに `.editorconfig` を置くのは当然として、`.gitconfig` の共有を導入せよ。
プロフェッショナルな `.gitconfig` の構成例
プロジェクト固有のルール（署名必須など）を強制する。
[user]
name = Your Name
email = your.email@company.com
signingkey =
[commit]
gpgsign = true # 署名なしコミットを禁止
[pull]
rebase = true # マージコミットで汚さない。リベース一択。
[alias]
lg = log –graph –oneline –all # 爆速で見やすいログ表示
—
4. 最後に：CI/CDパイプラインを止めるな
Bitbucket Pipelinesで認証エラーが出る場合、多くは「デプロイキーの期限」や「変数のスコープ」の問題だ。
現場の教訓：
1. 環境変数の管理: セキュリティトークンは絶対にリポジトリにコミットせず、Bitbucketの「Repository variables」でマスクして管理すること。
2. SSH Agent: パイプライン内でSSH接続を行う場合は、`bitbucket-pipelines.yml` の中で `ssh-agent` を適切に呼び出せ。
bitbucket-pipelines.yml の抜粋
pipelines:
default:
- step:
script:
- pipe: atlassian/ssh-run:0.4.1
variables:
SSH_USER: ‘ubuntu’
SSH_HOST: $SERVER_IP
COMMAND: ‘cd /app && git pull && docker-compose up -d’
スペシャリストからの提言
ツールが動かないとき、それは「ツールが悪い」のではなく、「ツールの思想を理解するチャンス」だ。認証エラーで止まったときこそ、`~/.ssh/config` や Gitのフックを見直し、環境をクリーンに保つ。
この地道なメンテナンスこそが、半年後の君たちの「圧倒的な開発速度」を支えることになる。
今日のトラブルシューティングは、明日の君たちの自由な時間だ。さあ、ターミナルに戻って、コードを書こう。