Skip to content

Create App from GitLab

Appliku integrates with GitLab using token-based authentication. You create a personal access token in GitLab and provide it to Appliku, which then accesses your repositories for deployment.

Prerequisites

  • A GitLab account (gitlab.com or self-hosted) with access to the repository you want to deploy
  • At least one server connected to Appliku

Step 1: Create a GitLab Access Token

Before connecting GitLab to Appliku, you need to generate an access token. Appliku supports both newer fine-grained personal access tokens and legacy/classic PATs. See GitLab Token Permissions below for exactly which permissions to choose.

  1. Log in to your GitLab account
  2. Go to Settings (click your avatar in the top-right corner) > Access Tokens
  3. Click Add new token
  4. Give the token a descriptive name (e.g., "Appliku deployment")
  5. Set an expiration date (or leave blank for no expiry, if your GitLab instance allows it)
  6. Choose the permissions described in GitLab Token Permissions
  7. Click Create personal access token
  8. Copy the token immediately: it will not be shown again

Step 2: Set Up GitLab Credentials in Appliku

  1. Go to Applications > Add Application > GitLab
  2. Click Setup Credentials
  3. Enter your GitLab access token
  4. If you are using a self-hosted GitLab instance, provide the instance URL
  5. Save the credentials

Appliku will verify the token and connect to your GitLab account.

Step 3: Create the Application

Once your GitLab credentials are configured:

  1. Select a repository from the list of accessible repositories. If you are using a fine-grained token scoped to specific projects, Appliku may not be able to list all of your groups and projects. That is expected: you can select the project directly, and Appliku validates access to it before saving.
  2. Choose a branch to deploy from
  3. Select a server or cluster for deployment
  4. Name your application
  5. Click Create Application

Push-to-Deploy

Push-to-deploy is supported for GitLab applications. Appliku registers a webhook in your GitLab repository that triggers a deployment on every push to the configured branch.

GitLab Token Permissions

Appliku works with both newer fine-grained personal access tokens and legacy/classic PATs. Fine-grained tokens are scoped to specific projects and permissions, so they are the recommended choice where your GitLab instance supports them.

When creating a fine-grained token, scope it to the project (or projects) you want Appliku to deploy from, and grant:

  • User read access (read the authenticated user): required when you save credentials. Appliku verifies the token by calling GitLab's GET /user, which fine-grained tokens gate behind User read access.
  • Repository read access: required for every deploy, so Appliku can clone and build the repository.
  • Branch read access for the selected project: required so Appliku can list branches when you create or change an application. See GitLab's fine-grained token REST permissions.
  • Webhook permissions (project hooks create, read, update, delete): required only for automatic push-to-deploy. See GitLab's webhook permissions.

If you omit webhook permissions, manual deployments still work; only automatic push-to-deploy setup is unavailable. When that happens, Appliku shows an actionable error and leaves push-to-deploy off rather than failing silently.

A fine-grained token scoped to one project is enough to create and deploy an app from that project, even if Appliku cannot list your other projects or groups. In that case, the new-app flow lets you enter the project ID or full path (for example group/project) directly, and Appliku validates access to it before continuing.

How credentials are validated

When you save GitLab credentials, Appliku verifies the token by reading the current authenticated user (GET /user). For fine-grained tokens this requires User read access; classic PATs cover it with the read_user scope (which api also includes). Appliku does not list your projects at save time, so a token scoped narrowly to selected projects saves successfully as long as it can read the authenticated user. Project-level permissions (repository read, branch read, webhooks) are checked later, against the specific project you select when creating or changing an application, so any missing permission surfaces with a message that names the project.

Legacy / classic PAT fallback

On GitLab.com and self-managed instances where fine-grained tokens are unavailable or behave differently, you can use a classic PAT:

  • read_repository is the minimum scope for cloning and building your code.
  • read_user is needed so Appliku can verify the token when you save credentials (the broader api scope includes it).
  • api may be required for project lookups and for creating or removing the push-to-deploy webhook, depending on your GitLab version and token type. Note that api is broad: it grants wide access, so prefer a fine-grained token when you can.

Self-managed GitLab

Fine-grained token availability and the token creation UI differ between GitLab versions. If your instance does not offer fine-grained tokens, use a classic PAT as described above. Remember to provide your instance URL when setting up credentials in Appliku.

Token expiry and revocation

If your token expires or is revoked, deployments and branch lookups fail until you update the credentials in Appliku with a new token.

Next Steps

After creating your application: