Bitbucket Integration

Abstract

You can upload content directly from Paligo to Bitbucket. Set up the Paligo to Bitbucket integration so that Paligo can connect to Bitbucket, and then you can publish.

paligo-to-bitbucket-small.jpg

Paligo has Continuous Integration (CI) support for Bitbucket. This means you can create content in Paligo, such as PDFs or an HTML help center, and publish it to Bitbucket. When the content is uploaded to Bitbucket, you can unzip it (automatically if you so choose) to make it instantly available live to your end users.

Before you can publish from Paligo to Bitbucket, you need:

  • A Bitbucket account

  • Basic Bitbucket knowledge and skills, including how to create a repository

  • A repository in Bitbucket. Paligo will upload published output to the repository. The output is uploaded as a zip file.

To set up Paligo to publish to Bitbucket:

This will allow Paligo to publish your output as a zip file to your chosen repository. You can unzip it manually or you can set up Bitbucket pipelines so that the the content file is unzipped automatically.

To set up Paligo to connect to Bitbucket, you need to have:

  • A Bitbucket account.

  • A repository to receive the zipped content that Paligo will upload when you publish.

    Paligo can upload content to the root of a repository, or to a folder inside it. It can also upload to a specific branch.

  • An app password that provides write permissions for the repository. To find out how to create app passwords in Bitbucket, see App Passwords

When you have a repository set up, you can connect Paligo to Bitbucket:

  1. Log in to Paligo via a user account that has administrator permissions.

  2. Select your profile name in the upper right corner to display a menu, and then select Settings.

  3. In the Settings view, select the Integrations tab.

  4. Find the Bitbucket settings and select Add.

    Note

    Add is only available the first time you set up an integration. After that, Add is replaced by Change.

    Paligo displays the Bitbucket integration settings:

    bitbucket_integration_settings.jpg
  5. Enter the Workspace ID. The workspace is where you create your repositories in BitBucket.

    To find out more about Bitbucket workspaces, see Workspaces.

    Note

    If the Workspace ID is identical to the Username, leave the Workspace field empty.

  6. Enter the Username for the Bitbucket account. Paligo will use this to log in to BitBucket. It is important that the account has write permissions for the repository (these are set for the account in BitBucket).

  7. Enter the App password. This is the password for accessing the app in BitBucket (and is defined in BitBucket).

  8. Enter the name of the Repository slug. This is the URL for your repository and is generated automatically by Bitbucket.

    To find out more about Bitbucket slugs, see What is a slug?

  9. Choose the Branch that Paligo will upload content to. The first time you set up the integration, select the branch button, so that Paligo can connect to Bitbucket using the settings you have provided. It will detect what branches are available. Then you can choose the branch from the dropdown list.

    The branch field in the integration settings. The branch button on the right of the field is highlighted.

    Paligo does not automatically update the integration settings page while it is open. This means that if you have the integration settings page open, and some new branches are added in Bitbucket, those new branches will not appear in the Branch field. But if you select the branch button, Paligo will update the settings page with the latest branch information.

  10. In the Destination folder field, enter the directory path for the folder that you want Paligo to upload the zip file to. This folder is inside the Bitbucket repository.

    For example:

    Folder 1/Folder 2/

    To upload the zip file directly to the root of the repository, leave the Destination field empty.

  11. Check the Use non-unique file name box if you want Paligo to use a consistent file name for the zip file. Each time Paligo publishes content via the integration, the zip file name will be the same.

    If you want Paligo to generate different names for the zip file each time, clear the checkbox.

  12. Select Save.

  13. Select the Change button for the Bitbucket integration.

  14. Select Test Settings to run a connection test. If the settings are correct, Paligo will show a green success notification.

    If the connection test fails, Paligo shows a red failure notification. Check each connection setting carefully, to make sure you have not made any mistakes and try again. If the connection test continues to fail, contact Paligo support for assistance.

When the connection is made, you can publish content from Paligo to a Bitbucket repository.

You can publish content from Paligo to Bitbucket, and the process is very similar to "regular" publishing. You create your publication and topics, and set up a layout for the type of output you want, such as PDF, HTML5, etc. Then you choose the publication settings and Paligo creates a zip file that contains your output content. The zip file is downloaded in your browser and it is also uploaded to your chosen Bitbucket repository.

To publish from Paligo to Bitbucket, you will use the Upload to Bitbucket option in the publishing settings. This option is only available if the Paligo Bitbucket integration settings are in place. You will also need to set up a publication and layout to create the output you want, for example, an HTML5 help center. With these in place, you can publish from Paligo to Bitbucket:

  1. In Paligo, select the options menu ( ... ) for the publication that you want to publish, and then select Publish.

    Publish document dialog showing settings for different output types, languages, profiling attributes, variables, and upload output.
  2. On the Publish document dialog, select the type of output you want, for example, HTML5.

  3. Choose the layout that you want to use for publishing. The settings in the layout are applied when Paligo generates the output.

  4. Choose the Languages to publish to. If you do not have any translations, you can only select the original/source language.

  5. If you have set filters (Profiling attributes) on topics or elements, and/or have used variables, choose which values to use for the publication. See Filters (Profiling) and Variables to learn how to use these features.

  6. In the Upload output section, check the Upload to Bitbucket box. By default, Paligo will upload the output to the repository and folder that are specified in the Paligo to Bitbucket integration settings.

    Upload output settings. There are options for Upload to GitHub, Upload via FTP, Upload to Bitbucket, and Upload to AWS S3. Upload to Bitbucket is selected.

    You can publish to a different branch and/or folder if required. Select the Edit icon next to Upload to Bitbucket, and then select the branch and/or folder on the Edit dialog.

    Bitbucket dialog for changing the branch and/or the destination folder for an individual publish.

    The settings you choose will only be used for this individual publishing process. Any future publishing will revert back to using the branch and folder that are defined in the integration settings.

  7. Select Publish document.

    Paligo generates the output, applying the settings from the layout and the Publication document dialog in the process. When the output is created, it is downloaded in your browser as a zip file. The zip file is also uploaded to your chosen repository branch and folder in Bitbucket. You can use a script to unzip the file automatically.

Note

This content is designed for developers who understand Bitbucket and know how to create SSH keys and Bitbucket Pipelines.

When you publish from Paligo to Bitbucket, Paligo uploads the content as a zip file. To use the Paligo content, you will need to unzip it in Bitbucket by using Bitbucket Pipelines. This involves:

  • Generating SSH keys for Bitbucket Pipelines

  • Adding a bitbucket-pipelines.yml file at the root of your repository.

To do this:

  1. Log in to your Bitbucket account and select the repository that you will use to publish content from Paligo.

  2. In the side menu, select Repository settings.

  3. In Repository settings, scroll down to the Pipelines section and select SSH Key.

  4. Select Generate Key to create a private and public key.

  5. Copy the public key.

  6. Select Your profile and settings .

  7. From the menu, select Personal settings to display the Personal Settings window.

  8. Select SSH keys.

  9. Select Add key and then paste in the public key you copied in step 5.

    Bitbucket will send you an email to let you know that you have added a key to your repository.

  10. Create a bitbucket-pipelines.yml file at the root of your repository.

  11. Edit the bitbucket-pipelines.yml file so that it unzips the content that Paligo uploads to the repository. We have provided examples for different scenarios, which you can use as a starting point.

Note

Please use the following examples at your own risk. You should be able to understand what the example does and what the steps do. Unfortunately, we cannot provide support if there are issues. Consider the examples as a proof of concept.

Example 1. Unzip Paligo content to same repository and same branch
image: php:7.2

pipelines:
    default:
        - step:
            script:
                - TARGET_BRANCH=$BITBUCKET_BRANCH 1
                - DESTINATION_FOLDER="." 2
                - apt-get update && apt-get install -y unzip git
                - cd $DESTINATION_FOLDER
                - FILE_COUNT=$(find ./ -name "*.zip" | wc -l)
                - if [[ $FILE_COUNT -gt 0 ]]; then
                - find ./ -name "*.zip" -exec unzip -o {} \;
                - rm *.zip
                - git add .
                - git commit -m "unzip the file from paligo and remove the zip file"
                - git push origin $TARGET_BRANCH
                - fi

1

TARGET_BRANCH - The branch name where unzipped content is pushed to. In this example, we use the environmental variable $BITBUCKET_BRANCH provided by Bitbucket, which contains the current branch name. See Variables in Pipelines for more information about environmental variables. Note that the branch you specify here must already exist.

2

DESTINATION_FOLDER - If you change the Destination Folder in Paligo's Bitbucket integration settings, you need to specify that folder here. Note that you must specify a relative path. For example, if you have specified paligo/output in the integration settings, you need to write paligo/output here. That path name is relative to the current folder where the script will be executed.

. What does this script do?
  1. Finds all files ending with .zip and unpacks them in the current folder.

  2. Removes all .zip files and push changes back to the current branch.


Example 2. Unzip Paligo content to same repository but a different branch
image: php:7.2

pipelines:
    default:
        - step:
            script:
                - TARGET_BRANCH="paligo-output" 1
                - DESTINATION_FOLDER="." 2
                - apt-get update && apt-get install -y unzip git
                - cd $DESTINATION_FOLDER
                - FILE_COUNT=$(find ./ -name "*.zip" | wc -l)
                - if [[ $FILE_COUNT -gt 0 ]]; then
                - TMP_DIR=$(mktemp -d -t paligo-XXXXXXXXXX)
                - find ./ -name "*.zip" -exec unzip -d $TMP_DIR -o {} \;
                - rm *.zip
                - git add .
                - git commit -m "remove the zip file"
                - git push origin $BITBUCKET_BRANCH
                - sleep 1
                - git checkout -b $TARGET_BRANCH && git pull
                - cp --recursive --force $TMP_DIR/* ./
                - git add .
                - git commit -m "unzip the file from paligo"
                - git push -f origin $TARGET_BRANCH
                - fi

1

TARGET_BRANCH - The branch name where unzipped content is pushed to. In this example, we use the branch name paligo-output.

2

DESTINATION_FOLDER - If you change the Destination Folder in Paligo's Bitbucket integration settings, you need to specify that folder here. Note that you must specify a relative path. For example, if you have specified paligo/output in the integration settings, you need to write paligo/output here. That path name is relative to the current folder where the script will be executed.

. What does the script do?
  1. Finds all files ending with .zip and unpacks them in a temporary folder.

  2. Removes all .zip files and push deletions back to the current branch.

  3. Changes branch.

  4. Copies all files from the temporary folder in the branch folder.

  5. Commits files.


Example 3. Unzip Paligo content to a different repository in the same project
image: php:7.2

pipelines:
    default:
        - step:
            script:
                - DESTINATION_FOLDER="."
                - TARGET_REPOSITORY="paligo-publications"
                - TARGET_BRANCH="output"
                - BITBUCKET_NAME='John Doe'
                - BITBUCKET_USERNAME='johndoe'
                - BITBUCKET_USEREMAIL='john.doe@company.com'
                - apt-get update && apt-get install -y unzip git
                - cd $DESTINATION_FOLDER
                - FILE_COUNT=$(find ./ -name "*.zip" | wc -l)
                - if [[ $FILE_COUNT -gt 0 ]]; then
                - TMP_DIR=$(mktemp -d -t paligo-XXXXXXXXXX)
                - find ./ -name "*.zip" -exec unzip -d $TMP_DIR -o {} \;
                - rm *.zip
                - git add .
                - git commit -m "remove the zip file"
                - git push origin $BITBUCKET_BRANCH
                - sleep 1
                - CLONE_DIR=$(mktemp -d -t clone-XXXXXXXXXX)
                - cd $CLONE_DIR
                - git clone git@bitbucket.org:$BITBUCKET_USERNAME/$TARGET_REPOSITORY.git $CLONE_DIR
                - git checkout -b $TARGET_BRANCH
                - cp --recursive --force $TMP_DIR/* ./
                - git config --global user.email "$BITBUCKET_USEREMAIL"
                - git config --global user.name "$BITBUCKET_NAME"
                - git add .
                - git commit -m "unzip the file from paligo and remove the zip file"
                - git push -f origin $TARGET_BRANCH
                - fi
. What does the script do?
  1. Finds all files ending with .zip and unpacks them in a temporary folder.

  2. Removes all .zip files and push deletions back to the current branch.

  3. Creates a new temporary folder and clones the target repository into that folder.

  4. Copies all files from the temporary folder in the branch folder.

  5. Commits files.