Since the latest release of our platform, I have been reviewing the customer experience to make sure customers find it easy to onboard and get to a green build for their projects. After analyzing the problems customers run into, I noticed five situations that are fairly common. I want to share these and ways to avoid them so you can get up and running as quickly as possible.
#1: Failed to find a YML file
When a repository from your source control account (GitHub, Bitbucket, etc.) is enabled as a project, Shippable listens for all commits, pull request, and releases events on the repository. When either one of these events occurs, an automatic build is triggered. The first thing Shippable does is to look for the
shippable.yml file at the root of your repository. If this is missing, you'll see an error in the console:
Reason: All build configuration on Shippable happens through the
shippable.yml file present at the root of your source control repository. If this file is missing, we don't know how to run your build and you see the error.
How to avoid: For any repository you enable on Shippable, create a
shippable.yml file at the root of your repo in your source control. At a minimum, include the language used in your repo, the version used & commands for tests that you are running. This example below shows a basic shippable.yml file that uses Node.js v5.3 and runs an npm test:
language: node_js node_js: - 5.3 build: ci: - npm install - npm test
Shippable builds all branches that have a shippable.yml at the root, unless they are explicitly excluded through the yml configuration.
shippable.yml reference guide is the best resource to learn what's possible with Shippable and explore the full capabilities supported on the platform.
#2: I cannot see my repositories in my Shippable account
When you sign into Shippable, you authorize it to access the repositories from your source control account. However, you might not see all your repositories as expected after signing in. Check out these three possible reasons and how you can get past this problem.
Reason #1 Private repos are not enabled: If you are signing in with your GitHub account, we only ask for access to your public repositories by default. You need to give Shippable explicit permissions to access your private repositories. This is a one-time setting: set this permission once and it will apply to all private repos in that source control account.
How to avoid: Go to your Account Settings. These settings are accessed from the gear icon on the top right hand navigation bar. Then, in the 'Accounts' tab under the 'Git Identities' section, click 'Enable':
After completing the auth flow for private repositories, click on 'Sync' under 'Account information'. You should now see your private repositories by navigating to your subscription on Shippable.
Reason #2 Your account has not been synced with the latest source control account permissions: While every code commit and pull requests instantly trigger events in Shippable, account syncs with your source control provider happen every four hours. In some scenarios you may need changes to permissions in your source control account to be seen immediately in Shippable. In these situations you can manually force sync your Shippable account with your source control provider.
How to fix: Go to your Account Settings by clicking the gear icon on the top right hand navigation bar. Then from the 'Accounts' tab under the 'Account Information' section, click 'Sync':
Reason #3 You are a Bitbucket user and you have Mercurial repositories: Shippable currently supports Git repositories only.
How to fix: Convert your Mercurial repo to a git repo. When the two accounts sync, you should see your converted git repo in the Shippable platform.
#3: Integration name specified in yml does not match integrations present in project settings
This issue can occur when you have configured an integration with either a docker registry provider or a notification provider in your yml. After you trigger a build, you get this error in the console:
Reason: Your integration needs to be configured in two places: in the Project Settings UI and in the
shippable.yml. The names used for the integration need to be exactly the same in both places. This error happens when the integration specified in your yml does not match the one specified in your Project Settings UI.
How to fix: Add the same integration in your Project Settings UI as the one you've specified in your yml.
This detailed documentation gives you more information on configuring integrations.
#4: Invalid RUN language:
You enable a repository and create a
shippable.yml file where you configure different settings including the language used in you repository. When a build gets triggered, you see this error:
Reason: Shippable supports several languages such as Node.js, Python, Ruby, Java, etc with official builds for each one. The language configured in the
shippable.yml file should have the correct syntax in order to be recognized.
How to fix: In the
shippable.yml file, under the
language section, configure the correct syntax for the language used in your project (repository). For example, use
node_js for Node.js,
python for Python. All supported languages and configuration syntax is available available here.
NOTE: You can continue to use Shippable even if you are using a language that does not have an official build image on our platform. You can use
language: none in the
shippable.yml file and provide a custom image for your build. Read the documentation on how to set it up.
#5: invalid yml format or Bad YML data
In this scenario, you enable a repo, create a
shippable.yml file and trigger a build on the Shippable platform. You get one of the two errors in the console shown below:
Reason: While both errors indicate that
shippable.yml has errors, there is a small difference between the two errors. The
invalid yml format is shown when the overall structure and syntax of the
shippable.yml file needs to be fixed. The
Bad YML data is shown when a particular line or section within
shippable.yml needs to be fixed.
How to avoid: For the
invalid yml format error, use online tools such as YAML Lint or YAML Online Parser to check the overall structure and syntax of the
shippable.yml file. For the
Bad YML data refer to our documentation on the
shippable.yml file for the specific section called out in the error.