Deployments with GitLab

GitLab is a DevSecOps platform for hosting Git repositories, reviewing code in merge requests, and running CI/CD pipelines. Teams use it on GitLab.com or run it on their own servers as GitLab Self-Managed, and organize projects into personal namespaces and nested groups.

How does the integration work?

GitLab is one of Appwrite's Git providers for Appwrite Sites and Appwrite Functions. You connect a GitLab account to your Appwrite project once, through GitLab's OAuth consent screen. One connection covers your personal namespace and every group you belong to, and each namespace appears as its own owner in the repository picker, next to owners from any other Git provider you have connected.

Each push to a connected repository can create a deployment:

• Production branch: the deployment builds and activates.
• Any other branch: the deployment builds but stays inactive. Sites get a preview link that only members of your Appwrite organization can open.
• Every build: Appwrite reports a commit status on GitLab and comments on the merge request with the deployment status, build logs, preview URL, and a QR code.

How to implement

To deploy from GitLab to Appwrite, there are several steps you must complete:

Step 1: Connect GitLab to your Appwrite project

For this step, you need to create an account on Appwrite Cloud or self-host Appwrite with GitLab configured.

In the Appwrite Console, open your project, go to Project settings > Git configuration, and click Connect GitLab. Approve GitLab's OAuth consent screen, and GitLab sends you back to the Console with the connection saved to the project.

You can also connect from an existing site or function under Settings > Version control (Git), or from the empty state of the site and function creation wizards when the project has no Git connection yet.

Step 2: Create a Site or Function from a GitLab repository

To deploy a site, go to Sites and click Create site. Under Connect Git repository, pick your personal namespace or a group, select the repository, and confirm the framework, install command, build command, and output directory. Add any environment variables, then deploy.

To deploy a function, go to Functions and click Create function. Under Connect Git repository, select your GitLab repository, set the root directory and entrypoint, and create the function.

To start from a template instead, the creation wizards can create a new GitLab project for you. The project lands in the namespace you pick, personal or group.

Step 3: Push to deploy

Push to your production branch, usually main, to build and activate a new deployment. Push to any other branch to get a deployment that builds without activating, along with a preview link to share in the merge request.

Build triggers limit which pushes deploy. Branch filters match branch names, and path filters match changed files, which keeps a push to docs/ from rebuilding a site in a monorepo:

apps/web/**
packages/ui/**
!docs/**

Deployment details link back to the commit, branch, and merge request on GitLab, using GitLab's own URL shapes.

Configure GitLab on self-hosted Appwrite

Self-hosted Appwrite needs its own GitLab OAuth application before it can connect to GitLab. To add one:

1. Create an OAuth application in GitLab. For one you own, select your avatar, then Edit profile > Access > Applications > Add new application. Group-owned and instance-wide applications work too.
2. Set the Redirect URI to https://<APPWRITE_DOMAIN>/v1/vcs/gitlab/callback, where <APPWRITE_DOMAIN> is your _APP_CONSOLE_DOMAIN, or _APP_DOMAIN when that is not set. Use http:// only if _APP_OPTIONS_FORCE_HTTPS is disabled.
3. Select the api and read_user scopes, which Appwrite requests to read repositories, register webhooks, and comment on merge requests. Save the application and copy its Application ID and Secret.
4. Add the credentials to your Appwrite .env file:

_APP_VCS_GITLAB_ENDPOINT=https://gitlab.example.com
_APP_VCS_GITLAB_CLIENT_ID=<APPLICATION_ID>
_APP_VCS_GITLAB_CLIENT_SECRET=<SECRET>
_APP_VCS_GITLAB_WEBHOOK_SECRET=<RANDOM_STRING>

Leave _APP_VCS_GITLAB_ENDPOINT empty to use GitLab.com. For your own GitLab instance, set it to a URL that both the Appwrite server and your browser can reach. The webhook secret can be any random string: Appwrite uses it when it registers a webhook on each repository you connect, and to validate the events GitLab sends to /v1/vcs/gitlab/events. If GitLab reaches Appwrite at a different address than your public domain, such as a Docker network address, set _APP_VCS_WEBHOOK_URL to that base URL.

Recreate the containers and check that the variables are applied:

docker compose up -d
docker compose exec appwrite vars

Read more about GitLab and Appwrite

If you would like to learn more about GitLab and Appwrite, we have some resources that you should visit: