Builds
What is a Build?
A Build is an executable product of your application. Based on a version of your code at a specific commit, composed of the Components defined in your Project Manifest, it is a ready to be deployed artefact.
Once a Build is created, its content can no longer be changed, so the Build contains your application in exactly the state it was in when the Build was pushed. Any changes to your code (new commits) require a new Build before they can be deployed. This ensures unique, immutable Builds that are linked to a unique commit ID, which can be promoted from Stage to Stage, fully reproducible and traceable. Pergola stores every Build, so you can always roll back to a previous version when needed.
That also means, your code should never contain:
- environment specific variables or configuration (e.g. IP or host names)
- sensitive data, like credentials
- any data that might bind your Build to a specific Stage, making it very difficult if not impossible to deploy anywhere else
Configuration might vary substantially across deploys, code should not. Instead, use Configuration Management for these type of data. This ensures strict separation of configuration from code.
How to create (push) a new Build?
To push a new Build you can use the Web UI or the CLI.
When you push a new Build, Pergola will go through all branches and for each branch it will look for a valid Project Manifest file. If it exists and there is a change (newer commit) since last Build, a new Build will be triggered. Otherwise, the branch will be skipped. So, pushing a Build might result in multiple Builds, one for each changed branch, or no Build at all when there are no changes or no Project Manifest in any of the branches.
If a Build fails, you can always check the Build logs. If a Build could not be started at all, e.g. due to connection issues to your code repository, Pergola will notify you about the exact reason that caused the failure via notifications.
Example for Web UI
Navigate to your Project on the start page or under the 'Projects' navigation and click on the 'BUILD NOW' button on the right side:
Example for CLI
pergola push build -p my-new-project
You can retrieve existing Builds, including the new one just pushed, via:
$ pergola list builds -p my-project
┌────────────────────────────────────────────────────────────────────────────┐
| build | commit | built at | status |
| ────────────────────────────────────────────────────────────────────────── |
| feat_new_v2_b1 | b0770c77b8f | Tue Jan 16 18:40:19 2024 (CET) | succeeded |
| master_b1 | 69cd543be9d | Tue Jan 16 18:40:19 2024 (CET) | succeeded |
| master_b2 | f2d256c7154 | 18 seconds ago | pending |
└────────────────────────────────────────────────────────────────────────────┘
The CLI provides a few more options, like building a specific branch only, or forcing a build even if there are no changes.
Code changes per Build
You can retrieve and review the code changes (git-log) that are included within a Build. The code changes can be accessed via the Web UI, by navigating to a specific Build:
Or, via the CLI's list commits command.
Security scans
Every successful Build is automatically scanned for potential vulnerabilities. Additionally, Builds that are currently deployed (on Stage) are scanned on a regular basis to keep the findings up-to-date. The scan utilizes official CVE databases and feeds that are refreshed on demand and at least once a day.
You can review the findings per Build via the Web UI:
Or, via the CLI's list vulnerabilities command.
How to deploy a Build?
You deploy a Build by issuing a new Release.