ValidateThis

GitLab CI: jobs config should contain at least one visible job

GitLab’s “jobs config should contain at least one visible job” error means the pipeline compiled to zero runnable jobs: everything is hidden, excluded by rules, or the YAML defines no jobs at all.

GitLab compiles .gitlab-ci.yml into a set of runnable jobs for the current pipeline (branch, tag, merge request, schedule). If that set is empty, the pipeline refuses to start with this error.

“Visible” means not hidden: any top-level key starting with a dot (like `.build-template:`) is a template, not a job.

Common causes

  • All jobs start with a dot (.job:) — dot-prefixed jobs are hidden templates and never run.
  • rules: or only/except conditions exclude every job for the current branch, tag, or pipeline source.
  • The file only defines stages, variables, include, or default — no actual job entries.
  • An include: pulls a template that also has no visible jobs, or the include path is wrong.
  • Indentation errors turn job definitions into nested keys of another block, so GitLab does not see them as jobs.

How to narrow it down

  • List your top-level keys: which of them have a script: (or trigger:) section and do not start with a dot? Those are your candidate jobs.
  • For each candidate, evaluate its rules:/only:/except: against the pipeline you are trying to run — a job excluded on this branch does not count as visible.
  • Use CI/CD → Pipeline editor → Validate in GitLab to see the compiled configuration, or paste the YAML into the CI config linter to catch structural mistakes first.

Examples

All jobs hidden (fails)
.build:
  script:
    - make build

.test:
  script:
    - make test

Dot-prefixed keys are templates. No runnable job exists.

Fixed: one visible job extends the template
.build-template:
  script:
    - make build

build:
  extends: .build-template
  rules:
    - when: always

The build job is visible and runnable; the template stays reusable.

How to fix

  • Ensure at least one top-level key is a job (has a script: section) and does not start with a dot.
  • Review rules:/only: conditions — temporarily replace them with when: always to confirm the job appears, then tighten.
  • Run the pipeline editor’s Lint (CI/CD → Editor → Validate) or paste the file into the CI config linter below to see structure errors.
  • Check that included templates resolve and define runnable jobs for your pipeline source (push, merge request, schedule).

Watch out

  • workflow: rules at the top of the file can cancel the whole pipeline before job rules are even evaluated — check both levels.
  • Indentation slips can nest a job under variables: or default:, silently hiding it from GitLab.

Related guides

Use our tool

Lint CI config

Advertisement

All guides