Bitbucket Integration

Abstract

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

Paligo has Continuous Integration (CI) support for Bitbucket Cloud. This means you can create content in Paligo, such as PDFs or an HTML help center, and publish it to Bitbucket Cloud. 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.

Note

Paligo does not have a direct integration with Bitbucket server. But with our API, your developers could set up a Bitbucket server integration themselves.

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

A Bitbucket Cloud 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 Cloud:

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.

Connect Paligo to Bitbucket Cloud

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

A Bitbucket Cloud 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 Cloud:

Log in to Paligo via a user account that has administrator permissions.
Sign in to Paligo using a user account that has administrator permissions.
Select the avatar in the top-right corner.
Select Settings from the menu.
Select the Integrations tab.
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:
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.
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).
Enter the App password. This is the password for accessing the app in BitBucket (and is defined in BitBucket).
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?
Choose the Branch that Paligo will upload content to.

If the Branch field is empty (or if a branch is missing), select the branch button to load the branches. Then choose the branch from the dropdown list.

Note

If the integration setting is open when new branches are added, those new branches will not appear in the Branch field unless the integration setting is reloaded.

Select the branch button, to reload the integration setting with the latest branch information.
As Destination folder, you enter the directory path for the folder that you want Paligo to upload content to.

To upload the zip file directly to the root, leave this field empty.
Control how Paligo names the output ZIP file with Use non-unique file name. It affects how the file is stored in the repository.
- Check the box to use a consistent filename for the output ZIP file each time you publish. If the repository already contains a file of the same name, the new file will replace the old one.
- Clear the box to add a number suffix to each output ZIP file when you publish. The repository will contain files for each output.
Select Save.
Select the Change button for the integration.
Select Test Settings to run a connection test.
If the settings are:
- Correct, Paligo shows a green success notification.
- Incorrect, 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 to Bitbucket.

Publish to Bitbucket

You can publish content from Paligo to Bitbucket Cloud, 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.

Note

You can use Bitbucket pipeline to automatically unzip the contents.

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:

Select the dotted menu (...) for the topic or publication in the Content Manager.
Select Publish.

Paligo displays the Publish document dialog.
Select the Type of output you want to publish (for example PDF, HTML, HTML5, Word, XML, eLearning, SCORM, or other).
Select the Layout to be used for your output.
Select the languages to be published.

Note

If no translations are available, only the Source Language will show. If you have multiple languages translated and approved, you can select which ones to include. Paligo will publish each language as a separate output.

For PDF output you can publish them as one multilingual publication, check the Combine selected languages box.
If your content is set up to use Filtering / Profiling, use the Profiling attributes section to apply them. [Optional]. If you do not use filtering, ignore this setting.

Select Edit and then choose the value for each filter that you want Paligo to use. For example, for Audience, choose Expert to include content that is marked as for expert users.

If you do not want to apply a filter, leave the field blank.

Select OK to add your chosen profiling attribute(s).
If your content is set up to use Variables , choose which variants to apply (optional).

Select Edit and then for each variable, choose the variant (value) that Paligo should apply to your publication.

If you do not want to apply a variable, leave the field blank.

Select OK to add the selected variables.
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.

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. 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.
Use the Output filename section to control the filename.

By default, Paligo will use the filename syntax that is defined in the System Settings.

To change the information included in the filename, enter your preferred format in the publishing settings. Default is: ID-Title-Format.
You can use:
- ID - The ID of the document.
- Title - The title of the publication or topic that you are publishing.
- Format - The name of the output format, for example, PDF or HTML5.
- Edit date - The date that the publication or topic was last edited.
- Branch label - The text from the branch label for the publication or topic. This only applies if your content has been branched and it has a branch label. For details, see Add or Edit Branch Labels.
- Unique value - A random string of characters, generated by Paligo, that is added to the filename to make it unique. This can stop the file from being overwritten by later publishes of the same document.
Tip

If you type @ into the field, Paligo displays a list of the available values and you can select from the list. To remove a value, click in it and use the delete key or backspace key to remove all of its characters.

Note

The filename shown in the top-right corner is a preview of the filename that Paligo will use when you publish.
Set the Optional Parameters (leave unchecked if you do not want these features):
- Save the output in Paligo - Check the box to save the zip file that Paligo creates when you publish. The zip file will be available from the Resource View and you can download it from the Saved Outputs tab. Clear the box if you don't want Paligo to store the zip file.
- Notify me - Check this box if you want Paligo to send you an email when the publication is ready. This is useful if you have very large publications that can take a longer time to process and publish.
- Make debug build - Check this box if you want Paligo to include a log file and link report. If there is an issue with your content, Paligo support may ask you to enable this feature so that they can use the log files to investigate.
Select Publish Document.

Paligo starts processing your content and applies your layout and publishing settings. The time that this takes varies depending on how much content you are publishing (the more content, the longer it takes).

A progress bar appears. Select the arrow to hide the progress bar and reopen it by selecting the progress clock in the top menu. To abort the publish, select the X.

The published output appears as:
- A ZIP file with the published output appears in the downloads folder on your computer.
  
  If you have altered your browser's settings to store downloaded files somewhere else, the zip file will be found there instead.
  
  If you are using a publishing integration, the zip file will also be sent to the relevant service.
- A link in the Activity Feed Panel to download the published content.
Note

To make the content available online, first unzip the file. You can then use the file locally or you can use an FTP client, such as Filezilla, to upload the unzipped content to a web server.

Tip

You can save your publishing settings and reuse them to achieve a smoother publishing process, see Publishing Settings. Any settings you save can also be used for Batch Publishing.

Unzip Paligo Content in Bitbucket Cloud

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 Cloud, 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:

Log in to your Bitbucket account and select the repository that you will use to publish content from Paligo.
In the side menu, select Repository settings.
In Repository settings, scroll down to the Pipelines section and select SSH Key.
Select Generate Key to create a private and public key.
Copy the public key.
Select Your profile and settings .
From the menu, select Personal settings to display the Personal Settings window.
Select SSH keys.
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.
Create a bitbucket-pipelines.yml file at the root of your repository.
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?

Finds all files ending with .zip and unpacks them in the current folder.
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?

Finds all files ending with .zip and unpacks them in a temporary folder.
Removes all .zip files and push deletions back to the current branch.
Changes branch.
Copies all files from the temporary folder in the branch folder.
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?

Finds all files ending with .zip and unpacks them in a temporary folder.
Removes all .zip files and push deletions back to the current branch.
Creates a new temporary folder and clones the target repository into that folder.
Copies all files from the temporary folder in the branch folder.
Commits files.

Bitbucket Integration

Note

Connect Paligo to Bitbucket Cloud

Note

Note

Note

Publish to Bitbucket

Note

Note

Tip

Note

Note

Tip

Unzip Paligo Content in Bitbucket Cloud

Note

Note

Search results