Set Up Bitbucket SSH Access on macOS

Create a dedicated SSH key, register its public half with Bitbucket, and configure SSH to use the matching private key for bitbucket.org. Using a host-specific entry avoids changing the identity used for unrelated Git servers.

Generate a dedicated key

Inspect existing keys first so you do not overwrite one you need. If the proposed filename already exists, choose another name and use it consistently below.

COPY
ls -la ~/.ssh
ssh-keygen -t ed25519 -C "YOUR_EMAIL" -f ~/.ssh/id_ed25519_bitbucket

Choose a passphrase. The command creates a private key and id_ed25519_bitbucket.pub; it does not create id_rsa merely because an older tutorial used that name.

Add it to Apple's agent and Keychain

COPY
eval "$(ssh-agent -s)"
/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519_bitbucket

Merge the following entry into ~/.ssh/config, preserving other host entries:

COPY
Host bitbucket.org
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519_bitbucket
  IdentitiesOnly yes

These commands follow the Apple OpenSSH workflow. If you use a different SSH implementation, check its flags and agent integration. Atlassian maintains the Bitbucket macOS SSH instructions.

Register the public key

COPY
pbcopy < ~/.ssh/id_ed25519_bitbucket.pub

Open your Bitbucket personal SSH key settings, add a label, and paste the public key. Never upload the private file or paste it into a support conversation.

Test the connection and remote

COPY
ssh -T git@bitbucket.org
git remote -v

For a first connection, verify the host-key fingerprint against Atlassian's published information before accepting it. A successful authentication response may say shell access is disabled; Bitbucket is providing Git access rather than an interactive shell.

An HTTPS Git remote will continue to use HTTPS credentials even when SSH is configured. Copy your repository's SSH clone URL from Bitbucket and deliberately change the remote if that is the workflow you want:

COPY
git remote set-url origin git@bitbucket.org:YOUR_WORKSPACE/YOUR_REPOSITORY.git

If authentication fails, use ssh -vT git@bitbucket.org to inspect which identity is offered. Check the registered key, account access to the repository, and any conflicting host entries. Remove sensitive paths or identifying information before sharing diagnostic output.

For deployment workflows after repository access is working, see CI/CD with AWS CDK and Azure-to-CodeCommit mirroring. This revision documents the configuration; it has not registered a key or changed your Git remotes.