How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitLab CI/CD

Deploying applications consistently across different CI/CD tools is a skill every engineer should master. This article focuses on how to use GitLab CI/CD to deploy a full stack Docker Compose application to Koyeb, a developer-friendly PaaS.

If you’ve already followed our GitHub Actions deployment guide for the same project, you’re in the right place. We won’t rehash the application structure, Dockerfiles, or Docker Compose file — those details remain unchanged. Instead, this guide zeroes in on the CI/CD configuration differences specific to GitLab.

You’ll learn how to:

• Set up your .gitlab-ci.yml file for Docker Compose deployments.
• Use the Koyeb CLI within GitLab runners.
• Trigger deployments by pushing to the main branch.
• Monitor and debug deployment from GitLab’s UI.

Table of Contents

• Prerequisites
• GitLab CI/CD Configuration
  • Getting the Koyeb API Token
  • .gitlab-ci.yml Explained
• Deploying to Koyeb
• Conclusion

Prerequisites

Before you begin, ensure the following:

• Review the supporting article: If you haven’t already, please read How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitHub Actions as it covers the core setup including Dockerfiles and Docker Compose configuration. This article will focus mainly on the GitLab CI/CD pipeline.
• A Koyeb account: Create a free account at https://www.koyeb.com if you don’t have one already.
• Koyeb API token: You will need this token to authenticate deployments from GitLab. Instructions on how to generate this token will be covered later in this article.
• GitLab repository: Your application code should be pushed to a GitLab repository with the necessary Dockerfiles and Docker Compose configuration included.
• Basic knowledge of GitLab CI/CD: Familiarity with GitLab pipelines and .gitlab-ci.yml syntax will help you follow along smoothly.
• Docker installed locally (optional): To build and test your Docker containers before pushing changes to GitLab.

GitLab CI/CD Configuration and Koyeb API Token Setup

Getting Your Koyeb API Token

To deploy your app to Koyeb via GitLab CI/CD, you’ll need an API token to authenticate deployment commands.

1. Log in to your Koyeb account.
2. Navigate to Account Settings → API Tokens.
3. Click Create New Token, give it a meaningful name (e.g., GitLab CI/CD Deployment), and generate the token.
4. Copy the token immediately — you won’t be able to see it again.

Adding the API Token to GitLab CI/CD Variables

1. Open your GitLab project.
2. Go to Settings → CI/CD → Variables.
3. Click Add Variable.
4. Enter the following:
   • Key: KOYEB_API_TOKEN
   • Value: Paste your copied Koyeb API token here
   • Enable Masked and Protected to keep the token secure.
5. Save the variable.

Understanding the .gitlab-ci.yml File

stages:
  - build-and-deploy

.standard-rules:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

koyeb-setup-and-deploy-job:
  stage: build-and-deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh
    - export PATH=$HOME/.koyeb/bin:$PATH
    - export KOYEB_TOKEN=$KOYEB_API_TOKEN
  script:
    - koyeb app create glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb
    - koyeb service create glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb --app glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb --git github.com/EphraimX/glowberry-global-tax-structure-simulator-gha-docker-compose-koyeb --instance-type free --git-builder docker --git-docker-dockerfile Dockerfile.koyeb --port 3000:http --route /:3000 --privileged

• stages: Defines the pipeline stages — here build and deploy. In this case, deployment happens in the build stage since it's a simple flow.
• .standard-rules: This reusable rule block ensures the job only runs on the default branch (usually main or master). It prevents unnecessary pipeline runs on other branches.
• koyeb-setup-and-deploy-job: The core job that builds and deploys the app to Koyeb.
  • stage: build — tells GitLab this job belongs to the build stage.
  • image: alpine:latest — uses a minimal Alpine Linux image as the runner environment.
  • before_script: Runs before the main script:
  • Installs curl to download the Koyeb CLI.
  • Downloads and installs the Koyeb CLI tool from the official repo.
  • Updates the system PATH to include the Koyeb CLI executable.
  • Sets the KOYEB_TOKEN environment variable from the secure GitLab variable KOYEB_API_TOKEN.
  • script: Runs the actual deployment commands:
  • koyeb app create <app-name> Creates a new app on Koyeb with the specified name.
  • koyeb service create <service-name> ... Creates a service under the app with the following parameters:
    • --app <app-name>: Associates the service with the app created above.
    • --git <repo-url>: Points to the GitHub repository where your code lives.
    • --instance-type free: Specifies the free tier instance for cost-effectiveness.
    • --git-builder docker: Instructs Koyeb to use Docker as the build method.
    • --git-docker-dockerfile Dockerfile.koyeb: Uses the provided Dockerfile for the build.
    • --port 3000:http: Exposes port 3000 as HTTP.
    • --route /:3000: Sets the routing path.
    • --privileged: Grants elevated permissions if required by your app.

Deploying to Koyeb

To deploy your full stack application to Koyeb using GitLab CI/CD, all you need to do is push your code changes to the main branch of your GitLab repository. The configured pipeline in .gitlab-ci.yml will handle the build and deployment automatically.

Here’s how you can do it from your local machine:

# Stage all your changes
git add .

# Commit your changes with a descriptive message
git commit -m "Deploy full stack app to Koyeb via GitLab CI/CD"

# Push changes to the main branch
git push origin main

Once the push is complete:

• GitLab will detect the commit and trigger the pipeline defined in .gitlab-ci.yml.
• Navigate to your project in GitLab, then go to Build > Pipelines to monitor the deployment progress.
• Click on the active pipeline to view detailed logs for each job step, helping you troubleshoot if any errors occur.

The pipeline executes the following automatically:

• Installs the Koyeb CLI.
• Authenticates using your KOYEB_API_TOKEN stored securely in GitLab CI/CD variables.
• Creates or updates your Koyeb app and service by referencing your repository and Docker Compose configuration.
• Deploys your app, making it accessible via the specified routes.

If you want to redeploy your application without new code changes, simply trigger the pipeline manually from the Pipelines page in GitLab.

Conclusion

In this guide, you learned how to deploy a full stack application to Koyeb using GitLab CI/CD with Docker Compose. By securely managing your Koyeb API token in GitLab’s CI/CD variables and configuring the .gitlab-ci.yml pipeline, you can automate your app’s build and deployment seamlessly.

This setup not only streamlines your deployment process but also ensures consistency and repeatability with every push to your repository. With this foundation, you can confidently iterate on your application while letting GitLab handle the deployment details.

Feel free to revisit the previous article for a deeper understanding of the Docker Compose setup and application structure. With this knowledge, you’re well equipped to adapt this workflow to other CI/CD platforms or customize it further for your project needs.

Found this guide helpful? Follow EphraimX for more hands-on DevOps walkthroughs. You can also connect with me on LinkedIn or explore more of my work on my portfolio.