What is a binding?#
A binding connects a repository to an environment and a pipeline. Which events start a run, whether PR merges are blocked, previews and the promote target are all set on the binding. A repository can have several bindings for different environments.
Bindings work the same way for GitHub, GitLab and Azure DevOps repositories. On this page "pull request" (PR) also covers GitLab merge requests; Azure DevOps calls them pull requests too. The console uses the label Merge request on GitLab bindings.
Prerequisites#
- A connected SCM: the EJO Cloud GitHub App installed for GitHub; a webhook saved under Settings > Webhooks for GitLab and Azure DevOps. See Connect your source control.
- At least one environment with a running agent. See Installing an agent.
- At least one pipeline. See Pipeline definition.
Create a binding#
-
On Delivery > Repositories, press Bind repository.
-
Pick the Provider and enter the repository. The field suggests names from the last scan of your SCM groups; you can also type a name that is not listed.
Provider Repository field Format GitHub GitHub repository owner/repo, for exampleacme/webGitLab GitLab repository path_with_namespace:group/projectorgroup/subgroup/projectAzure DevOps Azure Repos repository org/project/repo, for exampleacme/shop/webOn GitLab and Azure DevOps, pick the webhook that covers this repository from the Webhook secret list. Repositories connected through the GitHub App do not need it.
-
Pick the Environment to deploy to.
-
Pick the Commit / default pipeline. Pushes to the commit branch, manual runs, schedules and tags use this pipeline.
-
Optionally pick a separate PR pipeline, so that pull requests, for example, only run tests while a merge to main runs the full pipeline.
For repositories with a .ejo file, EJO can also create the binding. See The .ejo file.
Pipeline source#
| Option | Meaning |
|---|---|
| UI only — master is source of truth | The pipeline is edited and versioned in the console. |
| From repo — ejo.yaml is source of truth | The pipeline is read from the file in Pipeline file path (for example ejo.yaml). It syncs on webhook when the file changes; Publish in the console writes it back. On GitLab and Azure DevOps, EJO needs a token to read the file. |
You can pin a repository to a specific published version of a pipeline. The pin does not affect other repositories that use the pipeline.
Triggers#
In the Run pipeline on section of the binding page you choose which events start a run. At least one event or a schedule must be on.
| Option | When a run starts | Default |
|---|---|---|
| Push to a branch | On every push to the Commit branch. | On |
| Pull request (Merge request on GitLab) | When a PR targeting the PR target branch is opened, updated or reopened. Draft PRs do not start runs. | Off |
| Tag | A Git tag push; on GitHub, also a published release. | On |
| Schedule (optional) | On a 5-field cron expression in UTC, against the commit branch HEAD. | Empty (off) |
For example, 0 2 * * * runs every night at 02:00 UTC. Save your changes with Save triggers.
The events that feed these triggers on each SCM:
| Trigger | GitHub | GitLab | Azure DevOps |
|---|---|---|---|
| Push | Push | Push events | Code pushed |
| Pull request | Pull request: opened, synchronize, reopened, ready for review | Merge request events: open, reopen, update | Pull request created, Pull request updated |
| Tag | Tag push, Release (published) | Tag push events | Code pushed (refs/tags/...) |
| PR closed | Pull request: closed | Merge request: merge, close | Pull request updated: completed, abandoned |
A closed PR does not start a run; its preview, if any, is removed.
When a new push arrives for the same branch or PR, older runs for it that are still pending or running are cancelled and become SUPERSEDED. If the same webhook is delivered twice, no second deployment is created.
Manual runs#
The Run button on the binding page starts the pipeline by hand. With SHA (optional) left empty, the HEAD of the commit branch is used. If the pipeline defines inputs, the Run parameters form asks for the values. See Pipeline definition.
Pull requests from forks#
For PRs opened from a fork (on all three SCMs):
- The fork's
ejo.yamlis not used; the binding's stored pipeline runs. SECRET,K8S_SECRETandEXTERNAL_SECRETvalues and clone credentials are not handed out.- No pipeline OIDC tokens are issued and the automatic supply chain scan is skipped.
Merge gate#
With Block merge until this pipeline succeeds on, the PR pipeline becomes a merge gate. This also turns on the PR trigger.
The main (commit) pipeline stays WAITING until the PR pipeline of the merged commit succeeds. This wait runs on the EJO side on every SCM. EJO also blocks the merge button on the SCM side:
| SCM | What EJO does | Permission needed |
|---|---|---|
| GitHub | Adds a ruleset that requires the ejo status on the PR target branch. Private repositories on the GitHub Free plan have no rulesets, so the merge button may not be blocked there. |
The GitHub App's Administration permission |
| GitLab | Turns on Pipelines must succeed (only_allow_merge_if_pipeline_succeeds) on the project. The setting is project-wide and is not reverted when the merge gate is turned off. |
A token with the api scope |
| Azure DevOps | Creates a blocking Status branch policy on the PR target branch (genre ejo, name pipeline) and deletes it when the merge gate is turned off. |
Code (Read & write), Code (Status), Policy (Read & write) on the PAT |
If no GitLab token or Azure DevOps PAT is set at all, the merge gate cannot be turned on; saving the binding returns an error. If the permission is not enough, the SCM-side setting is not applied but the EJO-side wait still works. Details: Connect your source control.
Options that work together with the merge gate:
| Option | What it does |
|---|---|
| Required GitHub approving reviews | Added to the GitHub ruleset. 0 keeps the status check only; at most 6. GitHub only. |
| Also wait for the Review App URL | The merge gate waits until the PR run has a preview URL. The GitHub ruleset also requires the ejo/preview status; on Azure DevOps a second status policy for the name preview is added; on GitLab the wait is on the EJO side only. |
| Require a security scan step (Trivy or Sonar) in the PR pipeline | The PR run fails if the pipeline has no TRIVY_SCAN or SONAR_SCAN step, or if every scan step is skipped. |
| Block pull requests that break an API this service provides | The provides spec in .ejo is compared with the target branch. A removed operation or a new required parameter fails the ejo status. GitHub only. |
Warning: Also wait for the Review App URL needs a preview domain on the target environment; without one the merge gate waits forever. See Preview apps.
Previews#
With Preview on PR (isolated name, tear down when the PR closes) on, every PR is deployed under its own isolated name and removed when the PR closes. Preview label (optional) limits previews to PRs with that label (GitHub and GitLab; Azure DevOps ignores labels); Preview health path (optional) is the path requested before the preview counts as ready. Details: Preview apps.
Promote#
A successful run can be moved to another environment with Promote, using the same commit SHA.
- Promote to: the default target environment. It cannot be the bound environment. If left empty, the target is picked at promote time.
- Promote pipeline: the pipeline that runs on the target. If left empty and the target is Kubernetes, EJO deploys the recorded image digest without rebuilding.
- Auto-promote after a successful commit or manual run: starts the promote by itself after successful commit and manual runs. Promote runs are never promoted again.
Other options#
- Debug on failure: when a step fails, the agent keeps the container alive for an interactive debug session. See Deploy verification and rollback.
- Dependencies: a binding can wait for the latest successful run of another repository. With Wait for the same commit SHA on, the same commit is awaited; with it off, the latest success on the dependency branch is enough.