In this series of posts, we have been delving into the use of private Git repositories with OpenShift. As was covered in previous posts, the preferred mechanism for accessing a private Git repository is to use an SSH connection and a repository SSH key.
A repository SSH key, however, can only be used where the OpenShift cluster doesn't have access via an SSH connection blocked by a firewall. Being blocked by a firewall might occur if you're running an on-premise OpenShift cluster behind a corporate firewall, but using a Git hosting service such as GitHub.
In the case of SSH connections being blocked, it is necessary to fallback to using a personal access token and an HTTPS connection. In this post, we will look at how this is done when working with the GitHub service.
Creating a Personal Access Token
A personal access token is an alternative to the password you would use when accessing your account on the Git repository hosting service. Any number of access tokens can be created. You can create separate tokens for each separate client you may want to use to access your account. By using a separate token per client you can control what level of access each has, including whether they have read-only access, or can update repositories. A token for a specific client can be revoked without affecting other clients. Although what actions a specific client can do can be controlled, it would still be able to see all repositories that you as a user has access to.
To create a personal access token in GitHub, you need to visit the Settings of the user account and under Developer settings you will find Personal access tokens.
Select Generate new token, enter in a name as the Token description and enable the repo checkbox.
At this point in time, GitHub doesn't provide a way of setting the scope of a personal access token such that it has read-only access to repositories. Instead, one has to enable the repo scope which gives full control of private repositories.
Giving full control is not ideal as it means that anyone who gets control over the personal access token would also be able to write to 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.
If you are working at a company, the workaround is to use an organization in GitHub to hold any source code repositories you have. Next, create a machine user account on GitHub. This is an account which doesn't itself own any repositories. The machine user is then granted access as an external collaborator to the repository under the organization. When adding an external collaborator it is possible to override the access controls to indicate that the user has read-only access.
Therefore, it is possible to still restrict what can be done using the personal access token, but it requires a bit more setup. The ability to have read-only personal access tokens has been raised as a feature request with GitHub, and suggestions are that it may now be on the roadmap of new features they will be adding. It is possible that this will be supported at some time in the future. Either way, it would still be preferable to use a machine user that is granted access as an external collaborator only on specific repositories, as you can then better control what repositories it does have access to.
When you are done with setting the scopes for the personal access token, click on Generate token 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 GitHub settings.
Registering the Access Token with OpenShift
As for a repository SSH key, the next step is to register the personal access token as a secret with OpenShift. This can be done using the web console, or from the command line.
On the web console form for creating a secret, this time you need to set the following:
- Ensure that the Secret Type is Source Secret.
- Set the Secret Name. In this case we are using
- Ensure that the Authentication Type is Basic Authentication.
- Enter the name of the GitHub user the personal access token was created under, in the Username field.
- Enter the value of the personal access token in the Password or Token field.
- Enable the Link secret to a service account option.
- Ensure that the Service Account is set to
You could also 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-github --username=machineuser --prompt
$ oc secrets link builder user-at-github
We used the
--prompt option so that we are asked to enter in the access token as the password. You could instead use the
--password option and supply it on the command line.
Creating an Application from the Repository
The steps for creating an application from the private Git repository are similar to what was used previously for a repository SSH key. Select the name of the Source Secret when creating the application from the web console, or update the build configuration to include it if using the command line.
The URI of the repository can also be added as an annotation on the secret so that OpenShift can automatically make use of it when creating an application from the private Git repository. In this case we use the HTTPS version of the URI for the Git repository.
$ oc annotate secret/user-at-github \
Using the GitLab Hosting service
In this series of post,s we have so far covered the use of both repository SSH keys and personal access tokens when accessing a private Git repository on GitHub.
In the next part in this series, we will switch over to looking at using the GitLab hosting service instead of GitHub, and how the different credential types are setup with that service.
Read the Other Posts in this Series
- 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 4 - Hosting Repositories on GitLab
- Private Git Repositories: Part 5 - Hosting Repositories on Bitbucket