Usage

Why is my build not displaying?

This behavior can occur for several reasons that may or may not be visually apparent.

The first step to troubleshooting this issue requires viewing the webhook deliveries for the repository.

This can be accomplished by using one of the following methods:

• UI - Navigate to the https://vela.example.com/<org>/<repo>/hooks page for the repository
• CLI - Run the vela get hooks --org <org> --repo <repo> command for the repository

After finding the information for the webhook, please use the list below which includes details on how to resolve the issue.

Missing Webhook Signature

This behavior indicates the signature, used to verify authenticity of the webhook, for the repository has been removed.

To resolve the issue, the repository will need to be repaired which will recreate the webhook with a valid signature.

This can be accomplished by using one of the following methods:

• UI - Click the Repair button on the https://vela.example.com/<org>/<repo>/settings page for the repository
• CLI - Run the vela repair repo --org <org> --repo <repo> command for the repository

Payload Signature Check Failed

This behavior indicates the signature, used to verify authenticity of the webhook, for the repository has been corrupted.

To resolve the issue, the repository will need to be repaired which will recreate the webhook with a valid signature.

This can be accomplished by using one of the following methods:

• UI - Click the Repair button on the https://vela.example.com/<org>/<repo>/settings page for the repository
• CLI - Run the vela repair repo --org <org> --repo <repo> command for the repository

Repo Exceeded Build Limit

This behavior indicates the number of pending or running builds for the repository exceeded the concurrent build limit.

To resolve the issue, find a build with a pending or running status and cancel it (or wait for it to complete).

This can be accomplished by using one of the following methods:

• UI - Click the Cancel Build button on the https://vela.example.com/<org>/<repo>/<build> page for the repository
• CLI - Run the vela cancel build --org <org> --repo <repo> --build <build> command for the repository

Unable To Unmarshal YAML

This behavior indicates the pipeline can’t be compiled because it includes invalid syntax.

To resolve the issue, identify the incorrect syntax in the pipeline and update it with proper value(s).

This can be accomplished by using the vela validate pipeline CLI command in the directory where the pipeline is located.

Your Account Was Suspended

This behavior indicates the user who originally enabled the repository had their account suspended in the SCM.

To resolve the issue, the repository owner will need to be changed to an unsuspended user in the SCM.

This can be accomplished by using one of the following methods:

• UI - Click the Chown button on the https://vela.example.com/<org>/<repo>/settings page for the repository
• CLI - Run the vela chown repo --org <org> --repo <repo> command for the repository

Why is my build not running?

This behavior can occur for several reasons that may or may not be visually apparent.

The first step to troubleshooting this issue requires viewing the build object for the repository.

This can be accomplished by using one of the following methods:

• UI - Navigate to the https://vela.example.com/<org>/<repo> page for the repository
• CLI - Run the vela get builds --org <org> --repo <repo> command for the repository

After finding the information for the build, please use the list below which includes details on how to resolve the issue.

Build Is Pending

This behavior indicates the number of running builds for the system is greater than the number of workers available.

Unfortunately, the only way to resolve the issue is to wait until a worker becomes available to run your build.

Context Deadline Exceeded

This behavior indicates the amount of time the build was running exceeded the timeout for the repository.

To resolve the issue, optimize the pipeline to improve the performance and decrease the runtime for builds.

This can be accomplished by using one of the following methods:

• Update the pipeline to use rulesets which will limit the number of steps ran in the build
• Update the pipeline to use stages which will enable running steps concurrently

Invalid Reference Format

This behavior indicates the image key provided for a step in the pipeline is invalid.

To resolve the issue, identify the step with the incorrect image and update it with a proper value.

This can be accomplished by using the docker pull CLI command with the value for the image as the first argument.

Invalid Secret Path

This behavior indicates the key property provided for a secret in the pipeline is invalid.

To resolve the issue, explicitly define the secret depending on the type as outlined in the secret usage docs with all of the expected fields.

If you are using a secret that only defines name as the property and are receiving this error, you will need add the missing properties as this way of referencing a secret was deprecated in an older version of Vela.

For example:

secrets:
  - name: foo

and even

secrets:
  - name: foo
    key: foo
    engine: native
    type: repo

would need to be changed to:

secrets:
  - name: foo
+   key: <org>/<repo>/foo
+   engine: native
+   type: repo

Repo is not trusted

This behavior indicates the vela_executor_enforce_trusted_repos flag has been set by the Vela platform administrators, which allows only certain repositories to run privileged images.

To resolve the issue, identify the step attempting to run a privileged image and consider a workaround. Otherwise, work with your Vela platform administrators to add your repository to the allowlist.