Skip to main content

GitHub

Overview​

BeetleboxCI supports full GitHub integration, which is the recommended method for connecting GitHub repositories. GitHub can also be connected indirectly. This requires users to provide the URL of GitHub repositories (alongside credentials to access those repositories if needed).

Creating a GitHub App​

The first stage is to create a GitHub App for BeetleboxCI to connect to. You will need to have GitHub admin permissions for your organisation to do this.

  1. On the GitHub website, go to your GitHub Settings page and select Developer Settings. If you are part of an organisation, ensure you are on the organization's context and not your personal context.

  2. In Developer settings, please select GitHub Apps. This should open a new page and in this page please select New GitHub App. vcs_github_01

  3. In the Register new GitHub App, provide a name for your GitHub App under GitHub App name.

  4. For Homepage URL provide the URL of the BeetleboxCI server.

  5. Under Identifying and authorizing users provide the following for Callback URL: http://<your_server_url>/select_organisation

  6. Tick Request user authorization (OAuth) during installation.

  7. Under Webhook provide the following for Webhook URL:

http://<your_server_url>githubapp/receive/

  1. Under Permissions you will need to fill in three sections:

Under Repository permissions select the following:

  • Administration - Access: Read and write
  • Commit statuses - Access: Read and write
  • Deployments - Access: Read and write
  • Metadata - Access: Read-only
  • Pull requests - Access: Read and write
  • Webhooks - Access: Read and write

Under Organization permissions select the following:

  • Administration - Access: Read and write

Under Account permissions select the following:

  • Email addresses - Access: Read-only
  • Git SSH keys - Access: Read and write

In total six repository permissions, one organization permission and two account permissions should be selected.

  1. Afterwards select Create GitHub App at the bottom of the page.
  2. If registration was successful, you should recieve the following banner Registration successful. You must generate a private key in order to install your GitHub App. Click the link and generate a private key. This will download a private key that must be kept secure. You will need this private key for later.

Now that you have created the app, it is time to link to BeetleboxCI.

  1. To connect your GitHub account. Click on your profile on the right hand side of the BeetleboxCI webapp and select the Settings button.
  2. In the Settings tab select Linked Organisations. Under GitHub App Settings, fill in the following information:
  • App Id - the App ID that can be found in the GitHub App settings page.
  • Client Id - the Client ID that can be found in the GitHub App settings page.
  • Public link - the public link to your GitHub app which will be in the format: https://github.com/apps/<your_app_name>
  • Beetlebox URL - the URL of your Beetlebox installation.
  • Client Secret - For client secret, you need to generate a secret by selecting Generate a new client secret on the GitHub App settings page. Copy and save the secret to Client Secret.
  • Private key - Copy in the private key that you downloaded earlier.

vcs_github_04

Once finished, select Update Git Data.

  1. On the same BeetleboxCI page, select Configure Organisations. This will open a GitHub webpage asking for permissions, ensure All repositories is selected and then click Install & Authorize vcs_github_03
  2. This will redirect you back to BeetleboxCI. Make sure your organisation is selected and click Next. vcs_github_05
  3. This will redirect you back to the settings page. If everything has been successful, you should see your organization listed under Linked GitHub Organisations. vcs_github_06 Now anyone within your BeetleboxCI installation will now be able to add repositories directly from your GitHub organisation.

Adding a Public Github Repository to BeetleboxCI​

  1. On the pipelines page of BeetleboxCI in your browser: If you do not already have any pipelines in BeetleboxCI, click 'Create your first pipeline'. Otherwise, click "Create Pipeline" at the bottom of the pipelines page.
  2. In the following screen, fill in the following:

  • Project Name: [Name of your Github repository]

  • Repository URL: https://github.com/<username>/<repo_name>.git

    The authentication settings can be left blank since they are not necessary when adding a public repository.

  1. Click proceed. You will now be redirected to the pipelines page where you can see the project that you just created.

Adding a Private Github Repository to BeetleboxCI​

When you add a project from a private repository to BeetleboxCI, you will need to provide either:

  • A Github username and personal access token (https authentication)
  • A private SSH key to BeetleboxCI (plus adding the public key as a deploy key to the Github repository)

You can find more information further down this page about how to create personal access tokens and set up SSH keys.

  1. On the pipelines page of BeetleboxCI in your browser: If you do not already have any pipelines in BeetleboxCI, click 'Create your first pipeline'. Otherwise, click "Create Pipeline" at the bottom of the pipelines page.
  2. In the following screen, fill in the following:

  • Project Name: [Name of your Github repository]

  • Repository URL: https://github.com/<username>/<repo_name>.git or git@github.com:<username>/<repo_name>.git

  1. Also fill in either the "Authentication settings" section OR the "SSH Authentication" section. You will need need to use username and token authentication if you chose the https URL or SSH authentication if you chose the SSH URL.

  • Authentication Settings — Username: <Github username>

  • Authentication Settings — Password: <Github personal access token>

  • SSH Authentication — SSH private key

  1. Click proceed. You will now be redirected to the pipelines page where you can see the project that you just created.

Create a Github Personal Access Token​

To generate a personal access token for Github, you can follow this link. This personal access token can be used when creating pipelines in BeetleboxCI. When creating the token, you can specify the exact permissions this token will have.

SSH Keys​

Generate an SSH Key​

As an alternative to your username and a personal access token, you can generate an SSH key to authenticate access to private git repositories (given that the public key is added either to your Github account or just as a deploy key to the repository).

These commands are identical for both Windows and Linux.

  1. Open a terminal in Linux or Powershell in Windows.
  2. Input the command below, replacing the email address with the email that you have registered on Github:
ssh-keygen -t ed25519 -C "your_email@example.com"
  1. You will be prompted to enter a location to save the key. Press Enter to accept the default location which is shown.
  2. When prompted, enter a secure passphrase.
  3. Now two files will have been generated, and you can browse to the location where you saved them in Step 3 to find them. The file ending in .pub contains the public key which will need to be added as a deploy key either to you Github account or just to a Github repository. The private key can be added during the pipeline creation process in BeetleboxCI, as a means of authentication.

More information generating SSH keys for Github can be found on this link.

Add a public key (deploy key) to a Github repository​

This will provide authentication for just this repository.

  1. Browse to the repository which you want to add the key to.

  2. Click settings (if the settings option is not visible, then you do not have permissions to edit the settings of the repository)

  3. In the left-hand sidebar, click Deploy keys.

  4. Click Add deploy key on the top right.

  5. Choose a title for the deploy key that helps to remember what it is for, and paste the public key from the file you generated earlier.

    The public key will be similar to:

    ssh-ed25529 M3AGUEr7YVcArc00zSx3WWfY0Kxkb4tNL3BE8020XRwcrE6MBtUXQsKHab3rZt4qSEF62Z user@example.com

  6. You can optionally choose to allow write access, which will allow BeetleboxCI to perform pushes to the repository (at present, BeetleboxCI does not modify anything in your repository, but in future functionality of BeetleboxCI will be able to do this)

  7. Click Add key.

More information can be found in the deploy keys section of this document.

Add a public key to your Github account​

This will allow access to all the repositories which your account is able to access.

  1. Log in to Github

  2. In the top right hand corner of the web page, click your profile photo to show the drop-down menu and select the settings option.

  3. Click SSH and GPG keys on the left hand sidebar.

  4. Click New SSH key

  5. Provide a title for the key, and choose the Key type as Authentication key.

  6. Paste the public key into the Key field.

    The public key will be similar to:

    ssh-ed25529 M3AGUEr7YVcArc00zSx3WWfY0Kxkb4tNL3BE8020XRwcrE6MBtUXQsKHab3rZt4qSEF62Z user@example.com

  7. Click Add SSH key.

  8. If prompted, enter your Github username and password.

More information about adding SSH keys to your account can be found this this document.