Creating a Deploy to IBM Cloud button

The Deploy to IBM Cloud button is an efficient way to share your public Git-sourced app so that other people can experiment with the code and deploy it to IBM Cloud by using a toolchain. The button requires minimal configuration and you can insert it anywhere that supports markup. Anyone who clicks the button creates a cloned copy of the code in a new Git repository (repo) so that your original app remains unaffected.

When someone clicks your button, these actions occur:

If the person does not have an active IBM Cloud account, they must create an account. They can create a trial account or a real account.
The person can select a region, resource group, and app name by clicking the Delivery Pipeline icon. The suggested app name is the same as the toolchain name, which is constructed from the name of your original Git repo and the time. The toolchain name can also be edited.
A toolchain is created that includes a new private clone of your Git repo, a pipeline for building and deploying code changes, and an issue tracker.

If the .bluemix directory contains a toolchain.yml file, the file is used to specify the tool integrations for the toolchain. For more information about the toolchain.yml file, see Creating custom toolchain templates.
If the app requires a build file, the build file is detected automatically and the app is built.
If a pipeline is configured for the build and deployment process, a pipeline.yml file is used to deploy the app.
If the app requires a container, a pipeline.yml file that defines the IBM Cloud Kubernetes Service and a Dockerfile that defines an image are used to deploy the app in the IBM Cloud Kubernetes Service.
The app is deployed to the IBM Cloud organization that the person selected.

Examples of the button

See an app button example for a public Git Repos and Issue Tracking repo:

See an app button example for a public GitHub repo:

Creating a button

To create a Deploy to IBM Cloud button, copy and modify one of the following snippet templates. Specify a Git repository and branch in the URL.

Creating a button in HTML

To create a button in HTML, copy this snippet and insert a public Git repository URL and branch.

<a href="https://cloud.ibm.com/devops/setup/deploy?repository=<git_repository_URL>&branch=<git_branch>"><img src="https://cloud.ibm.com/media/docs/images/icons/Deploy_to_cloud.svg" alt="Deploy to IBM Cloud" target="_blank"></a>

If you don't include the branch parameter in your snippet's repository URL, the Deploy to IBM Cloud button defaults to the repository's master branch.

Creating a button in Markdown

To create a button in Markdown, copy this snippet and insert a public Git repository URL and branch.

[![Deploy to IBM Cloud button](https://cloud.ibm.com/media/docs/images/icons/Deploy_to_cloud.svg)](https://cloud.ibm.com/devops/setup/deploy?repository=<git_repository_URL>&branch=<git_branch>)

If you don't include the branch parameter in your snippet's repository URL, the Deploy to IBM Cloud button defaults to the repository's master branch.

Using the button snippets

After you create a Deploy to IBM Cloud button snippet, you can insert it into blogs, articles, wikis, readme files, or anywhere else you want to promote your app.

When you customize the snippet for your Deploy to IBM Cloud button, consider that both of the templates use a default path to an external button image in SVG format and in English. If you prefer to store the image locally, you can download the image and store it in your Git repo. Adjust the path to use the relative location of the image.

Repository considerations

Review these considerations for the repo that you use in your Deploy to IBM Cloud button.

Build file requirements

If the app must be built before it can be deployed, you must include a build file in your repo. If a build script file is detected in the root directory of the repo, an automated build of the code is triggered before deployment.

Supported builders include:

Ant: build.xml, which builds output to the ./output/ folder
Gradle: /build.gradle, which builds output to the . folder
Grunt: /Gruntfile.js, which builds output to the . folder
Maven: /pom.xml, which builds output to the ./target/ folder

Pipeline file requirements

To configure the pipeline for the toolchain in a .bluemix directory, include a pipeline.yml file. For each pipeline.yml file in that directory, a pipeline is created when the toolchain is instantiated.

To create a pipeline file, consult the example file in the Creating custom toolchain templates documentation. Just as when you define a pipeline in the web interface, you define a pipeline in text by creating stages and jobs, setting inputs and environment variables, and adding scripts. You can also see a number of more complex pipeline files in this demonstration project.

Container Dockerfile requirements

To deploy an app in a container by using the IBM Cloud Kubernetes Service, you must include a Dockerfile in the root directory of the repo and, in a .bluemix directory, include a pipeline.yml file.

The Dockerfile acts as a kind of build script for the app. If a Dockerfile is detected in the repo, the app is automatically built into an image before it is deployed in a container. If the app itself must be built before the app is built into an image, include a build script for the app and a Dockerfile.

To learn more about creating Dockerfiles, see the Docker documentation. To learn more about Kubernetes, see IBM Cloud Kuberenetes Service.

To create a pipeline.yml manually that is specifically for containers, see the examples in GitHub.