--- layout: integration title: Deployments with GitLab description: Deploy Appwrite Sites and Functions on every push to a GitLab repository date: 2026-11-06 featured: false isPartner: true isNew: true cover: /images/integrations/deployments-gitlab/cover.avif category: deployments product: vendor: GitLab description: "GitLab is a DevSecOps platform that hosts Git repositories, merge requests, and CI/CD pipelines on GitLab.com or on your own servers." platform: - 'Self-hosted' - 'Cloud' --- [GitLab](https://about.gitlab.com) 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](/docs/products/sites) and [Appwrite Functions](/docs/products/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](/docs/products/sites/previews) 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. **Self-hosted Appwrite** Self-hosted Appwrite 2.0 and later can deploy from GitLab.com or from your own GitLab instance once you give the server a GitLab OAuth application. See [Configure GitLab on self-hosted Appwrite](#configure-gitlab-on-self-hosted-appwrite). # 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](/sign-up) or [self-host Appwrite](/docs/advanced/self-hosting) 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](/docs/products/sites/deploy-from-git#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: ```txt 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:///v1/vcs/gitlab/callback`, where `` 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: ```env _APP_VCS_GITLAB_ENDPOINT=https://gitlab.example.com _APP_VCS_GITLAB_CLIENT_ID= _APP_VCS_GITLAB_CLIENT_SECRET= _APP_VCS_GITLAB_WEBHOOK_SECRET= ``` 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: ```bash 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: - [Announcing GitLab support for Appwrite Sites and Functions](/blog/post/announcing-gitlab-support) - [Deploy Sites from Git](/docs/products/sites/deploy-from-git) - [Deploy Functions from Git](/docs/products/functions/deploy-from-git) - [Preview deployments](/docs/products/sites/previews) - [Configure GitLab as an OAuth 2.0 provider](https://docs.gitlab.com/integration/oauth_provider/)