🦊 GitLab Integration

GitLab hosts generated platform code and runs CI/CD pipelines

Overview

We use GitLab.com for:

• Code hosting: Generated Angular platforms
• CI/CD: Build and deploy pipelines
• API access: Programmatic project management

Account Details

API Integration

Authentication

# Environment variable
GITLAB_API_TOKEN=glpat-xxxxx

Token permissions required:

• api - Full API access
• read_repository - Clone repositories
• write_repository - Push code

GitLab Provider Service

Located at: apis/backend-api/src/app/git-provider/gitlab-provider.service.ts

@Injectable()
export class GitLabProviderService implements GitProviderService {
  // Core operations
  async createRepository(name, options);
  async pushFiles(repoPath, files, message);
  async createBranch(repoPath, branchName);
  
  // Pipeline operations
  async createPipeline(repoPath, ref);
  async getPipeline(repoPath, pipelineId);
  async getPipelineJobs(repoPath, pipelineId);
  async cancelPipeline(repoPath, pipelineId);
  async retryPipeline(repoPath, pipelineId);
}

Common Operations

Create Project

const project = await gitlabProvider.createRepository('client-platform', {
  namespace_id: 122455722, // gograbspace group
  visibility: 'private',
  initialize_with_readme: true
});
// Returns: { id: 12345, path: 'gograbspace/client-platform', webUrl: '...' }

Push Files

const files = [
  { path: 'src/main.ts', content: '...' },
  { path: 'angular.json', content: '...' },
  { path: '.gitlab-ci.yml', content: '...' }
];

await gitlabProvider.pushFiles(
  'gograbspace/client-platform',
  files,
  'feat: initial platform generation'
);

Trigger Pipeline

const pipeline = await gitlabProvider.createPipeline(
  'gograbspace/client-platform',
  'main' // branch ref
);
// Returns: { id: 12345, webUrl: '...', status: 'pending' }

Monitor Pipeline

const status = await gitlabProvider.getPipeline(
  'gograbspace/client-platform',
  12345
);
// Returns: { id: 12345, status: 'success', finishedAt: '...' }

CI/CD Configuration

Generated .gitlab-ci.yml

The GitLabCIGeneratorService creates CI configurations:

# Auto-generated by GitLabCIGeneratorService
stages:
  - install
  - build
  - deploy
  - notify

variables:
  NODE_VERSION: "20"
  PNPM_VERSION: "9"
  CLOUDFLARE_PROJECT_NAME: "client-platform"

default:
  image: node:${NODE_VERSION}-alpine
  cache:
    key:
      files:
        - package.json
        - yarn.lock
    paths:
      - node_modules/

install:
  stage: install
  script:
    - corepack enable
    - yarn install --immutable
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

build:
  stage: build
  needs: [install]
  script:
    - yarn build --configuration=production
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

deploy:production:
  stage: deploy
  needs: [build]
  image: node:${NODE_VERSION}-alpine
  before_script:
    - npm install -g wrangler
  script:
    - wrangler pages deploy dist/browser --project-name=$CLOUDFLARE_PROJECT_NAME
  environment:
    name: production
    url: https://${CLOUDFLARE_PROJECT_NAME}.pages.dev
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

notify:success:
  stage: notify
  needs: [deploy:production]
  script:
    - |
      curl -X POST "https://api.gograb.space/api/build-pipeline/webhook" \
        -H "Content-Type: application/json" \
        -d '{"status": "success", "pipelineId": '$CI_PIPELINE_ID'}'
  allow_failure: true

Pipeline Variables

Set in GitLab Project → Settings → CI/CD → Variables:

Identity Verification

GitLab.com requires identity verification to run CI/CD pipelines.

Verification Steps

1. Go to https://gitlab.com/-/identity_verification
2. Choose verification method:
   • Credit card (no charge)
   • Phone number
3. Complete verification
4. Pipelines will work immediately

Why Required?

GitLab implemented this to prevent:

• Cryptocurrency mining abuse
• CI/CD resource abuse
• Spam/malicious builds

API Endpoints Used

Testing

Connection Test

yarn test:gitlab

Output:

🔍 Testing GitLab Connection...
   URL: https://gitlab.com
   Token: glpat-xxxxx...

1️⃣  Testing authentication (GET /user)...
   ✅ Authenticated as: gograb-space (admin GoGrab)
   
2️⃣  Testing group access (GET /groups)...
   ✅ Can access groups. Found 1 owned group(s)
      - gograbspace (ID: 122455722)

3️⃣  Testing project access (GET /projects)...
   ✅ Can access projects.

🎉 All tests passed!

E2E Pipeline Test

yarn e2e:pipeline

Tests:

• Create project in gograbspace
• Push files with CI config
• Trigger pipeline
• Verify pipeline created
• Cleanup test resources

Troubleshooting

403 Forbidden on Group Creation

Cause: Token lacks group creation permission

Fix: Use existing group gograbspace instead

Pipeline Not Triggering

Causes:

1. Identity verification not completed
2. No .gitlab-ci.yml in repo
3. CI disabled for project

Fix: Complete verification at https://gitlab.com/-/identity_verification

"No Runners Available"

Cause: Using tags that don't match shared runners

Fix: Remove tags: from job definitions or use docker tag

Rate Limits

GitLab.com API limits:

Monitor with response header: RateLimit-Remaining

See Also

• GitLab API Documentation
• Cloudflare Pages
• Pipeline Overview