Integrate deployment into Bitbucket

On this page

We're removing this page for the AtlasCamp release.

We believe end-users of Bitbucket want to go from code to deployment as quickly as possible. Integrators who have a deployment target of some kind can follow the instructions below to create a working example for Bitbucket end-users to follow. These working examples will help end-users create their own pipelines targeting your service.

Create a recipe for your service

  1. Public example repository. The build capability is tightly coupled to Bitbucket repositories; hence, you will need to create a public Git repository in Bitbucket (currently only Git repositories are supported) and push sample code. The focus is on deployment so the sample code can be as simple as a Hello World application. Based on the popularity of languages in Bitbucket, the order of preference by language is: PHP, Java, C#, everything else. If you do use a C# project, then it must be Mono for Linux since Windows is not available for Bitbucket Pipelines.

  2. Add a build. A build is where your deployment step will run. Follow the configuration steps to create a build and add a build configuration file to the sample repository. If you specify no image, the build will use the default image which includes many languages. You can choose to use a different base image from Docker Hub such as php:7, java:8, or mono:4. For small dependencies (like zip/unzip), feel free to inject dependencies via apt-get or curl. If you feel comfortable with Docker and publishing to Docker Hub, you can even create your own image. The configuration flow will provide you an example configuration file but here's a Python variation for quick reference.

    Python build configuration example
    image: python:3.5
    pipelines:
      default:
        - step:
            script:
                - pip install tox
                - tox -e py35
                - deploy.bash

    Bash requirement

    Currently, builds require Bash in the Docker container; hence, most Alpine-based images are not a good fit with Bitbucket builds at this time. Unlike Ubuntu-based images, Alpine-based images do not have Bash by default.

    Building Docker images

    Currently, builds cannot create Docker images. Please use Docker Hub's automated build to publish Docker images.



  3. Upload a build artifact to your service. The focus of the example repository is how your deployment works. Write a bash script to deploy the build result to your service (deploy.bash in the above example). You may use cat to generate a POST payload and curl the your API. Alternatively, you might use plugins to a build tool (like Phing, Maven, MS Build, etc) but please still write a bash wrapper. End-users might not use this kind of wrapper, but having one outside the YAML configuration file makes it easier to copy/paste. It should: document the expected environment variables, map environment variables to the build tool or POST payload, and call the build tool or curl.

    Example bash script
    #!/bin/bash -e
    
    # PYPI_USERNAME - (Requried) Username for the publisher's account on PyPI
    # PYPI_PASSWORD - (Required, Secret) Password for the publisher's account on PyPI
    
    cat <<'EOF' >> .pypirc
    [pypi]
    repository=https://pypi.python.org/pypi
    username=$PYPI_USERNAME
    password=$PYPI_PASSWORD
    EOF
    python setup.py sdist bdist_wheel upload

    Exit Bash on error

    It is highly recommended that you use the -e switch as shown in the above example. This causes Bash to exit on the first error.



  4. Extract environment variables. Environment variables help parameterize deployment. You should extract environment variables from the cat and curl for authentication, repo details (commit sha, branch, owner, repo slug), or other things that might be better configured via build server. For each environment variable, write a short comment line in the bash script to document the meaning for end-users. Ideally, the bash script could be copied to any end-user project and the environment variables would be sufficient to avoid modifying the script.

Tell us about it

We want to make a list of repositories as recipes for end-users to use as starting points. Also, we're looking for input from you about Bitbucket Pipelines. Do you need special environment variables from Bitbucket Pipelines? How could we extend the UI/UX to provide easier flow from Bitbucket into your service? What Bitbucket Pipelines features could make it easier and faster for end-users to integrate with your product?

Last modified on May 12, 2016

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.