Private Git Repositories: Part 5 - Hosting Repositories on Bitbucket

In this series of blog posts on using a private Git repository with OpenShift, we have covered how to use a repository hosted on both GitHub and GitLab. We will now close out this series of posts by looking at how to use a private Git repository hosted on Bitbucket.

Ensure you have read the prior posts for background on how to create repository SSH keys, register any credentials with OpenShift and create an application from the private Git repository. These can be found at:

• Private Git Repositories: Part 1 - Best Practices
• Private Git Repositories: Part 2A - Repository SSH Keys
• Private Git Repositories: Part 2B - Repository SSH Keys
• Private Git Repositories: Part 3 - Personal Access Tokens
• Private Git Repositories: Part 4 - Personal Access Tokens

Using a Repository SSH Key

The first step to using a private Git repository on Bitbucket using a repository SSH key is to generate the SSH key pair to be used with that repository. Remember that it is recommended to use a distinct SSH key pair. Do not use your primary identity SSH key as you will need to upload the private key file of the SSH key pair to OpenShift.

$ ssh-keygen -C "openshift-source-builder/repo@bitbucket" -f repo-at-bitbucket -N ''

To register the repository SSH key with your private repository on Bitbucket, go to the Settings for the repository.

On Bitbucket the repository SSH key is referred to by the term Access key. Search down the settings page and find the Access keys section and select it.

Click on the Add key button. In the popup window, give the key a name and paste in the contents of the public key file from the SSH key pair. This is the file with the .pub extension, which in our case is called repo-at-bitbucket.pub.

Bitbucket repository SSH keys provide read-only access and it is not possible to enable them as having write access.

Upon clicking on Add key the key will be registered for the repository.

The next step is to create a secret in OpenShift to hold the private key of the SSH key pair. We showed how to do this using both the web console and command line in prior posts. When using the command line, this was done by creating the secret:

$ oc secrets new-sshauth repo-at-bitbucket --ssh-privatekey=repo-at-bitbucket

and enabling access to the secret from the builder service account:

$ oc secrets link builder repo-at-bitbucket

In order that OpenShift knows the secret is for our private Git repository, we annotate the secret with the complete SSH form of the URI for the repository, including ssh://, dropping any user credentials in the URI in the process.

$ oc annotate secret/repo-at-bitbucket \

    'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.org/grahamdumpleton/private-repo.git'

We can then deploy our application from the private Git repository.

$ oc new-app httpd~git@bitbucket.org:grahamdumpleton/private-repo.git --name mysite

Using a Personal Access Token

If the OpenShift cluster you are using is located behind a corporate firewall and SSH connections are blocked, you need to use a personal access token and HTTPS connection instead.

From the web interface of Bitbucket browse to your Bitbucket settings.

On Bitbucket a personal access token is referred to by the term App password. Search down the settings page and find the App passwords section, click on it and then Create app password.

Enter in a name for the token and enable the Read checkbox against Repositories. This ensures that a user of the personal access token has read-only access to any repositories.

They will still be able to read any repositories the account has write access to. This is one of the reasons why read-only repository SSH keys bound to a specific repository are preferred.

When you are done with setting the permissions for the personal access token, click on Create and you will be shown the value of the token. Make sure you make a copy of this as you cannot view it later on in the Bitbucket settings.

We now need to create the secret from the command line using the oc secrets new-basicauth command, remembering to run oc secrets link to allow the builder service account to use it.

$ oc secret new-basicauth user-at-bitbucket --username=machineuser --prompt
$ oc secrets link builder user-at-bitbucket
 

You will need to supply the name of the user account which the personal access token was created under. It is better to create a machine user account for an organization, which has access to the repository, rather than use a personal user account.

The --prompt option means you will be asked to enter in the access token as the password. You could instead use the --password option and supply it on the command line.

Next, annotate the secret with the URI for the repository. Because we are using a personal access token, this will be the HTTPS URI for the repository.

$ oc annotate secret/user-at-bitbucket \

    'build.openshift.io/source-secret-match-uri-1=https://bitbucket.org/osevg/private-repo.git'

We can then deploy our application from the private Git repository.

$ oc new-app httpd~https://bitbucket.org/osevg/private-repo.git --name mysite

Using Private Git Repositories

This is the end of the blog series on using private Git repositories with OpenShift. In these posts we have covered the different protocols and credential types you can use to access a hosted Git repository, as well as listed some best practices around the credential type used. We looked at setting up and using repository SSH keys and personal access tokens with the major Git repository hosting services. The main posts used GitHub as the hosting service, but we also summarised key details when using GitLab and Bitbucket in subsequent posts.

Links to all the posts are:

• Private Git Repositories: Part 1 - Best Practices
• Private Git Repositories: Part 2A - Repository SSH Keys
• Private Git Repositories: Part 2B - Repository SSH Keys
• Private Git Repositories: Part 3 - Personal Access Tokens
• Private Git Repositories: Part 4 - Hosting Repositories on GitLab
• Private Git Repositories: Part 5 - Hosting Repositories on Bitbucket