Deploy from GitLab
Use a GitLab repository as the source of an HTTP application. Each person connects their own gitlab.com account to Zenifra, picks the repository from a list, and publishes the application on every push to the branch. For a GitLab hosted by your institution (self-managed), the organization owner connects the instance with a token.
Required permissions
| Action | Who can do it |
|---|---|
| Connect your own GitLab account | Anyone who can create projects in the organization or in a team |
| Connect a self-managed GitLab with a token | Organization owner (owner) |
| Create an HTTP project | project.create on organization:* |
| Change the repository, branch, or Auto-deploy | project.source.update on project:<project-id> |
| Start a New build | project.deploy.trigger on project:<project-id> |
| Read builds and logs | project.logs.read on project:<project-id> |
owner has full access. assistant, member, and API Keys need the matching grants.
Connect your GitLab account
- In the Console, open the Account page.
- On the GitLab card, click Connect GitLab.
- GitLab shows the authorization screen for the Zenifra application, which requests the
apiandread_repositoryscopes. Authorize the access. - You return to the Account page, and the card now shows Connected as with your GitLab username.
The read_repository scope lets Zenifra read the code for each build. The api scope is needed to list your repositories, create the webhook on the GitLab project that notifies Zenifra of each push and merge request, and comment on merge requests.
The connection is yours: only you use your repositories through it, even if other people in the organization also connect GitLab. The owner can see in Git provider connections that the connection exists, but cannot use, replace, or revoke it. The connection applies to the active organization; in another organization, connect GitLab again.
Connect GitLab works with gitlab.com accounts. For a GitLab hosted by your institution, see Self-managed GitLab.
Create the project
- In the Console, click Create project and choose HTTP Application.
- Under Source and port, in Project Source, choose Git repository, and in Git provider, choose GitLab. If you have not connected your account yet, the form shows the Connect GitLab button.
- In Repository, pick one of your repositories. Use Search repository to filter the list and Load more repositories to see the next ones. The list shows the projects where you have the Maintainer role or higher, including projects in subgroups such as
group/subgroup/app. - Choose the Branch and turn on Auto-deploy to publish on every push to that branch.
- Choose the runtime, the version, and the commands. If the application lives in a subfolder of the repository (monorepo), fill in Root directory, for example
backendorapps/api; see Root directory and monorepos. - Click Create Project. The first build starts when the project is created and uses the selected branch.
The Maintainer role is required because GitLab only allows creating webhooks from that role up. Follow the build in Build logs on the project page: the history shows the status of each build, the output of each command, and the published commit. Details about commands, dependencies per runtime, and cache apply to every Git provider and are in GitHub Deployment.
Publish updates
| Mode | What starts a deployment |
|---|---|
| Auto-deploy on | A push to the selected branch |
| Auto-deploy off | Only a New build in the Console |
With Auto-deploy on, Zenifra creates the webhook on the GitLab project that reports each push. Pushes to other branches, tags, and deleted branches do not start a build.
To publish manually, open Build logs and click New build. It publishes the branch configured for the project; in Exact commit SHA (optional) you can pin a specific commit by entering the full 40-character SHA. To publish another branch, change the branch in the Git repository section.
GitLab projects do not have the By Tag and By Release modes: publishing by tag or release is only available for GitHub and Forgejo projects.
Change the configuration after creation
On the project page, the Git repository section shows the repository, the branch, and whether Auto-deploy is on. In Select or change repository, choose another repository, another branch, or change Auto-deploy, then click Save repository. Changing the repository or the branch starts a new build. In Build commands, adjust the runtime, version, commands, and Root directory.
Merge request previews
GitLab projects on paid plans can create Preview Environments automatically for merge requests. Zenifra's legacy Free plan does not include previews.
In the project's Preview Environments section, choose Configure previews, turn on Enable Preview Environments and Enable automatic GitLab previews, and choose the Preview target branch. That branch decides which merge requests create previews and does not change the branch of the main application.
For merge requests from the same project that target the selected branch:
- opening or reopening the merge request creates the
pr-<number>preview, which the Console shows asMR !<number>; - a new commit on the merge request updates the preview;
- editing the merge request, for example changing its target branch, makes Zenifra re-evaluate the preview;
- closing or merging it ends the preview;
- merge requests from forks or targeting other branches do not create previews;
- merge requests opened before you turned the feature on join the flow on their next relevant event.
Merge request comment
Zenifra keeps a single comment on each merge request and edits it on every change instead of adding new comments:
- when the preview is up, the comment shows the preview URL and its time to live (TTL);
- if the preview build fails before its first deployment, the comment asks you to check the build log in the Console; the next push tries again;
- when the preview ends, the comment shows the date and time it ended, in Brasília time (UTC-3).
The text is written in Portuguese and English. The comment is posted with the GitLab account of the person who connected the GitLab used by the project.
Self-managed GitLab
If your institution hosts its own GitLab (self-managed), the organization owner connects the instance with a token:
- In Create project, choose Git repository and the GitLab provider.
- Click Your institution runs its own GitLab? Connect with a token.
- Fill in Instance address (for example
https://gitlab.yourinstitution.edu), Connection name, Repository path (group/app, without the domain), and Access token. - Click Connect repository.
Use a personal, group, or project access token with the api and read_repository scopes. To create the webhook for Auto-deploy and previews, the token needs the Maintainer role on the project. The free gitlab.com plan only offers personal access tokens; group and project tokens depend on your GitLab plan or installation.
The instance must answer over HTTPS with a valid certificate and be reachable by Zenifra. For Auto-deploy and previews, it must also be able to deliver webhooks to Zenifra over HTTPS. This connection does not list repositories: enter the path of each repository when you create the project.
The token connection belongs to the organization: other members pick it in Connection when they create projects. To change the token or revoke the connection, open Account > Git provider connections and use Replace credential or Revoke. Never put the token in URLs, Git commands, or project environment variables.
Disconnect or reconnect GitLab
To disconnect, click Disconnect on the GitLab card of the Account page. Zenifra removes the webhooks it created on your GitLab projects and revokes the access. Projects created with that connection stop receiving deployments, and applications already running keep working. To deploy again after disconnecting:
- On the Account page, click Connect GitLab.
- In each affected project, open Git repository, use Select or change repository, pick the repository again, and click Save repository.
- If no build starts, click New build in Build logs.
If the authorization expires or you revoke the Zenifra application in your GitLab settings, the card shows Reconnect GitLab and builds fail with the message "GitLab no longer authorizes access to this repository. Reconnect GitLab on the Account page and deploy again.". In that case, click Reconnect GitLab on the Account page and authorize again. Zenifra reuses the same connection, and projects receive deployments again with no other change. To deploy the commit that failed, click New build in Build logs.
GitLab event delivery
The webhook Zenifra creates on the GitLab project delivers pushes and merge requests:
- each delivery carries the webhook secret token; deliveries without the right token are rejected with
401. Do not change the webhook secret token in GitLab; - each delivery body can be up to 100 KB; larger deliveries are rejected;
- each webhook can deliver up to 120 events per minute; the excess is rejected with
429.
A rejected delivery does not start a build. Check the delivery history in Settings > Webhooks on the GitLab project and publish the commit with a New build.
Current limitations
- GitLab projects cannot publish by tag or release;
- Connect GitLab works with gitlab.com; a self-managed GitLab uses the token connection;
- merge requests from forks do not create previews;
- SSH sources, submodules, and Git LFS are not supported.
Frequently asked questions
My repository does not show up in the list. What should I check?
Make sure you have the Maintainer role or higher on the GitLab project and that the connected account is the one with that access. Use Search repository or Load more repositories when you have many projects.
The push was accepted, but no build started. Why?
Make sure Auto-deploy is on and that the push went to the configured branch. Then check in Settings > Webhooks on the GitLab project whether the delivery reached Zenifra. GitLab disables a webhook that fails several times in a row; in that case, re-enable it in GitLab.
Why was the merge request comment posted with my username?
Preview comments use the GitLab account of the person who connected the GitLab used by the project.
The build failed with "Reconnect GitLab". What should I do?
GitLab no longer accepts the authorization. Follow the steps in Disconnect or reconnect GitLab.
Next steps
Last updated on
Automatic Deployment with GitHub Actions
Set up automatic deployment to Zenifra with GitHub Actions: build the OCI image, push it to Docker Hub or AWS ECR and update the project on version tags.
Deploy from Forgejo
Deploy from Forgejo to Zenifra: connect your instance with a token, pick the repository and publish by branch, tag or release, with pull request previews.