Skip to main content

Troubleshooting

This section contains a list of common solutions to usage and operation pitfalls.

I need the Pergola API endpoint for the CLI​

To use the command line tool, you need to specify the Pergola API endpoint it should connect to.

This is best done by executing this command:

pergola login --endpoint <API-ENDPOINT>

Your API endpoint can be found in the Web UI by clicking the CLI-button in the topbar next to your name.

CLI button

See pergola login for more details.

My Build fails​

Builds might fail for several reasons. And sometimes, it can be quite tiresome until you find the actual cause and have a suitable fix for it. Here are a few hints where to look at and how to troubleshoot your failed Build.

To get more details about your failed Build, navigate to the 'Projects' page in the Web UI to find all recent Builds.

There are two sources for gathering information from:

  1. Click on the Notificatons button to see if there is an error message related to your Build.
  2. Click on the failed Build itself to see the full Build logs for a more detailed root cause analysis.

Notification button

Check here for help on common Build issues:

Git repository not accessible​

Pergola clones your Git-Repository for every build. It needs read/view permissions on your repository which need to be granted by you or your Git administrator.

For private repositories, you can get an SSH Key via the CLI and add it to your Git repository.

See also Git configuration for further details.

Project Manifest not found or invalid​

Pergola needs a Project Manifest file (pergola.yaml or pergola.json) in the root-folder of your git repository.

Manifest file in git

For troubleshooting and examples, please refer to the Tutorials and the Project Manifest documentation.

You can validate your Project Manifest with the CLI's validate command, even before pushing to Git, on your local machine.

Docker build fails​

If the Build fails during the Docker build process, you should first check the Build logs.

You can also try to reproduce the Build failure locally by running docker build on your machine, like:

docker build . -t my-app-test-build

I need to run my background job now​

A background job in Pergola comes as a scheduled Component, that runs at pre-configured points in time.

In order to run it now, you can stop (disables scheduling) and then start it again with the 'Also run job immediately' checkbox to re-enable scheduling and run it immediately:

Start dialog

See here for more examples.