Your first pipeline

In this tutorial you register a runner for a project, add a .gitlab-ci.yml to a repository, push it and watch the pipeline run in an isolated Docker container.

Forge reads its pipeline definition from a file named .gitlab-ci.yml at the root of the repository. The syntax follows GitLab CI/CD, with an explicit supported subset: anything Forge does not support is rejected with an error that names the line and column, never silently ignored. The full list is in the CI configuration reference.

Before you start

• A repository in an Orbit project (Your first repository).
• A machine with Docker where you can run a runner. Forge runs your jobs on runners that you register; there are no shared runners.

1. Register a runner

A runner is a standalone program that you run on your own machine. It is registered per project: it only takes jobs from that project.

1. Project administrators open the project’s runners in Code / CI and register a new runner.

2. Give the runner tags if you want to route jobs to it. A runner can be limited to tagged jobs only, or to jobs on protected branches and tags only.

3. Copy the runner token. It is shown once, and Forge stores only a hash of it. If you lose it, an administrator can reset the token: the old token stops working at once, and running jobs keep their own lease tokens.

4. Start the runner with that token. Each runner reports its version, capabilities and online status; the runner list shows them.

Jobs run with the Docker executor: each job gets a fresh, non-root container with a read-only root filesystem, no Docker socket and no service credentials. More in Runners.

2. Enable automatic pipelines (optional)

Automatic pipelines are opt-in, and each trigger is enabled independently:

• branch pushes (from the web editor and from native Git pushes),
• tag pushes,
• merge requests (when a request is opened or reopened, and on pushes to its source branch).

Until a trigger is enabled you can still run a pipeline by hand from the web interface.

3. Write .gitlab-ci.yml

.gitlab-ci.yml

stages:
  - build
  - test

build:
  stage: build
  image: alpine:3.20
  script:
    - echo "Building"
    - mkdir -p out && echo "hello" > out/result.txt
  artifacts:
    paths:
      - out/
    expire_in: 1 day

test:
  stage: test
  image: alpine:3.20
  script:
    - cat out/result.txt

Every job needs script. image can be set per job or once under default:. Jobs in a later stage receive the artifacts of the earlier stages unless you narrow it with dependencies or needs.

4. Check it before you push

Lint a configuration without pushing. The same parser that pipelines use runs on your machine.

Terminal

orbit-forge ci lint .gitlab-ci.yml

In development

The local orbit-forge ci lint command and its -dry-run (which lists which jobs your rules would run, make manual or exclude) are working but still in development. You can also lint in the pipeline editor, where includes are resolved against the repository.

orbit-forge ci lint prints located errors as file:line:col: message, or the stage and job plan. Exit status 0 means valid, 1 invalid, 2 that it could not run. Add -json for machine-readable output. It reads include: local files from the repository root.

5. Push and watch

Terminal

git add .gitlab-ci.yml
git commit -m "Add a pipeline"
git push origin main

If branch pipelines are enabled, a pipeline appears under Code / CI. Open it to see stages and jobs. Each job panel offers Retry job and Cancel job. A job that waits shows why: the jobs it needs, a delayed start, a resource group, no runner of the project with its tags, or every matching runner paused or busy.

Job logs show ANSI colours and collapsible sections. They are rendered as text, never as HTML. Job logs are kept up to 4 MiB; each retry keeps the log of the earlier attempt in the attempt history, and no job claims more than three automatic attempts.

Skip a pipeline

Add [skip ci] or [ci skip] to the commit message to skip automatic push, tag and merge request pipelines for that commit. git push -o ci.skip skips every pipeline from that push. Other push options are rejected before any ref changes. Running a pipeline by hand from the web ignores the markers.

Artifacts and test reports

• artifacts:paths, expire_in, name, exclude and expose_as (listed on the merge request) are supported, with archive browsing and single-file downloads in the web UI.
• artifacts:reports:junit becomes per-job test results on the pipeline page; dotenv reports pass variables to jobs that need the producer; coverage: /regex/ reads the percentage from the last match in the job log.
• Caches (cache:) and project artifact quotas are covered in the reference.

Next

• CI configuration reference
• Runners