feat(linter): glint explain, GL042 rules:if: reachability, GL043 inherit completeness
- `glint explain <RULE>`: new subcommand printing rule description, rationale, bad-YAML example and fix for every GL001–GL043 rule. `glint explain` (no arg) lists all rules with ID, severity, title. Rule IDs are case-insensitive. - GL042 (rules:if: evaluated reachability): warns when every rules:if: condition evaluates to false given the values of variables declared in the pipeline YAML, making the job statically unreachable. Conservative: only fires when all referenced variables are declared in YAML; predefined CI_* / GITLAB_* variables are skipped to avoid false positives. - GL043 (inherit: completeness): warns when inherit: default: is declared but there is no default: block in the pipeline (dead declaration), or when the list form names fields not set in the default: block. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,819 @@
|
||||
package linter
|
||||
|
||||
// RuleEntry holds the human-readable documentation for a single lint rule,
|
||||
// shown by 'glint explain <RULE>'.
|
||||
type RuleEntry struct {
|
||||
Title string // short title (one line)
|
||||
Severity Severity // Error or Warning
|
||||
Description string // what triggers the rule and why it matters
|
||||
Example string // YAML snippet that triggers the rule
|
||||
Fix string // corrected YAML
|
||||
}
|
||||
|
||||
// RuleCatalog maps stable rule IDs to their documentation entries.
|
||||
var RuleCatalog = map[string]RuleEntry{
|
||||
RuleNoStages: {
|
||||
Title: "no stages defined",
|
||||
Severity: Warning,
|
||||
Description: "The pipeline has no 'stages:' block. GitLab falls back to the " +
|
||||
"built-in default stages (build, test, deploy), which may not match your " +
|
||||
"intended job ordering.",
|
||||
Example: `# No stages: block
|
||||
build-job:
|
||||
script: make build
|
||||
|
||||
test-job:
|
||||
script: make test`,
|
||||
Fix: `stages:
|
||||
- build
|
||||
- test
|
||||
|
||||
build-job:
|
||||
stage: build
|
||||
script: make build
|
||||
|
||||
test-job:
|
||||
stage: test
|
||||
script: make test`,
|
||||
},
|
||||
|
||||
RuleWorkflowWhen: {
|
||||
Title: "workflow.rules.when invalid value",
|
||||
Severity: Error,
|
||||
Description: "'workflow.rules[n].when' only accepts 'always' or 'never'. Any " +
|
||||
"other value (such as 'on_success' or 'manual') is invalid and will cause " +
|
||||
"the pipeline to fail to create.",
|
||||
Example: `workflow:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
when: on_success # invalid here`,
|
||||
Fix: `workflow:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
when: always`,
|
||||
},
|
||||
|
||||
RuleMissingScript: {
|
||||
Title: "missing required 'script' field",
|
||||
Severity: Error,
|
||||
Description: "Every non-trigger, non-pages job must define 'script:' (or 'run:' " +
|
||||
"for CI Steps). A job with no script will fail immediately when GitLab tries " +
|
||||
"to run it.",
|
||||
Example: `my-job:
|
||||
stage: test
|
||||
image: python:3.12
|
||||
# Missing script:`,
|
||||
Fix: `my-job:
|
||||
stage: test
|
||||
image: python:3.12
|
||||
script: pytest`,
|
||||
},
|
||||
|
||||
RuleUnknownStage: {
|
||||
Title: "job references undeclared stage",
|
||||
Severity: Error,
|
||||
Description: "The job's 'stage:' value does not match any name in the pipeline's " +
|
||||
"'stages:' list. GitLab will reject the pipeline configuration.",
|
||||
Example: `stages:
|
||||
- build
|
||||
- test
|
||||
|
||||
deploy-job:
|
||||
stage: production # not in stages:
|
||||
script: ./deploy.sh`,
|
||||
Fix: `stages:
|
||||
- build
|
||||
- test
|
||||
- production
|
||||
|
||||
deploy-job:
|
||||
stage: production
|
||||
script: ./deploy.sh`,
|
||||
},
|
||||
|
||||
RuleOnlyRulesConflict: {
|
||||
Title: "'only:' and 'rules:' used together",
|
||||
Severity: Error,
|
||||
Description: "'only:' and 'rules:' are mutually exclusive. Using both on the " +
|
||||
"same job is a configuration error that prevents the pipeline from being " +
|
||||
"created.",
|
||||
Example: `my-job:
|
||||
only:
|
||||
- main
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
script: echo conflict`,
|
||||
Fix: `# Remove only: and use rules: exclusively
|
||||
my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == "main"
|
||||
script: echo ok`,
|
||||
},
|
||||
|
||||
RuleExceptRulesConflict: {
|
||||
Title: "'except:' and 'rules:' used together",
|
||||
Severity: Error,
|
||||
Description: "'except:' and 'rules:' are mutually exclusive. Using both on the " +
|
||||
"same job is a configuration error that prevents the pipeline from being " +
|
||||
"created.",
|
||||
Example: `my-job:
|
||||
except:
|
||||
- tags
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
script: echo conflict`,
|
||||
Fix: `my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_TAG
|
||||
when: never
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
script: echo ok`,
|
||||
},
|
||||
|
||||
RuleDeprecatedOnly: {
|
||||
Title: "'only:' / 'except:' deprecated",
|
||||
Severity: Warning,
|
||||
Description: "'only:' and 'except:' are deprecated in favour of 'rules:'. " +
|
||||
"GitLab may remove support for these keywords in a future major version. " +
|
||||
"'rules:' is more expressive and supports variable references, merge-request " +
|
||||
"conditions, and fine-grained 'when:' control.",
|
||||
Example: `my-job:
|
||||
only:
|
||||
- main
|
||||
script: ./deploy.sh`,
|
||||
Fix: `my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == "main"
|
||||
script: ./deploy.sh`,
|
||||
},
|
||||
|
||||
RuleInvalidWhen: {
|
||||
Title: "'when:' has invalid value",
|
||||
Severity: Error,
|
||||
Description: "Job-level 'when:' accepts: on_success, on_failure, always, " +
|
||||
"manual, delayed, never. Any other value is rejected by GitLab.",
|
||||
Example: `my-job:
|
||||
when: sometimes # invalid
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
when: on_success
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleDelayedNoStartIn: {
|
||||
Title: "'when: delayed' without 'start_in:'",
|
||||
Severity: Error,
|
||||
Description: "'when: delayed' requires a 'start_in:' duration (e.g. " +
|
||||
"'30 minutes', '1 hour'). Without it GitLab rejects the job configuration.",
|
||||
Example: `my-job:
|
||||
when: delayed
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
when: delayed
|
||||
start_in: 30 minutes
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleStartInNoDelayed: {
|
||||
Title: "'start_in:' without 'when: delayed'",
|
||||
Severity: Error,
|
||||
Description: "'start_in:' is only meaningful when 'when: delayed'. Setting it " +
|
||||
"alongside any other 'when:' value is a configuration error.",
|
||||
Example: `my-job:
|
||||
when: on_success
|
||||
start_in: 30 minutes # only valid with delayed
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
when: delayed
|
||||
start_in: 30 minutes
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidParallel: {
|
||||
Title: "'parallel:' value invalid",
|
||||
Severity: Error,
|
||||
Description: "'parallel:' must be an integer between 2 and 200 (inclusive), " +
|
||||
"or a map with a 'matrix:' key for matrix jobs. Values outside this range " +
|
||||
"or the wrong type are rejected by GitLab.",
|
||||
Example: `my-job:
|
||||
parallel: 1 # must be 2–200
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
parallel: 5
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidRetry: {
|
||||
Title: "'retry:' value invalid",
|
||||
Severity: Error,
|
||||
Description: "'retry:' accepts an integer 0–2 or a map with optional 'max:' " +
|
||||
"(0–2) and 'when:' keys. Values outside this range are rejected.",
|
||||
Example: `my-job:
|
||||
retry: 5 # max is 2
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
retry: 2
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidRetryWhen: {
|
||||
Title: "'retry.when:' has invalid failure type",
|
||||
Severity: Error,
|
||||
Description: "'retry.when:' must be a recognised GitLab CI failure type " +
|
||||
"(e.g. script_failure, runner_system_failure) or 'always'. Unknown " +
|
||||
"values are rejected.",
|
||||
Example: `my-job:
|
||||
retry:
|
||||
max: 2
|
||||
when: disk_full # not a valid failure type
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
retry:
|
||||
max: 2
|
||||
when: runner_system_failure
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidAllowFailure: {
|
||||
Title: "'allow_failure:' invalid value",
|
||||
Severity: Error,
|
||||
Description: "'allow_failure:' must be a boolean (true/false) or a map with " +
|
||||
"an 'exit_codes:' key. Other forms are rejected by GitLab.",
|
||||
Example: `my-job:
|
||||
allow_failure: maybe # must be true/false or map
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
allow_failure: true
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidInterruptible: {
|
||||
Title: "'interruptible:' is not a boolean",
|
||||
Severity: Error,
|
||||
Description: "'interruptible:' must be a boolean (true or false). Other types " +
|
||||
"are rejected.",
|
||||
Example: `my-job:
|
||||
interruptible: yes # must be a YAML boolean true/false
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
interruptible: true
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleTriggerWithScript: {
|
||||
Title: "trigger job also defines 'script:'",
|
||||
Severity: Error,
|
||||
Description: "Jobs with a 'trigger:' key (downstream pipeline triggers) cannot " +
|
||||
"use 'script:'. These are mutually exclusive — a trigger job has no runner " +
|
||||
"environment to execute scripts in.",
|
||||
Example: `trigger-job:
|
||||
trigger:
|
||||
project: mygroup/myproject
|
||||
script: echo this will fail`,
|
||||
Fix: `trigger-job:
|
||||
trigger:
|
||||
project: mygroup/myproject`,
|
||||
},
|
||||
|
||||
RuleInvalidTrigger: {
|
||||
Title: "trigger: map missing 'project:' or 'include:'",
|
||||
Severity: Error,
|
||||
Description: "When 'trigger:' is a map it must specify either 'project:' " +
|
||||
"(downstream project trigger) or 'include:' (dynamic child pipeline). " +
|
||||
"Without one of these keys GitLab cannot determine what to trigger.",
|
||||
Example: `trigger-job:
|
||||
trigger:
|
||||
strategy: depend # missing project: or include:`,
|
||||
Fix: `trigger-job:
|
||||
trigger:
|
||||
project: mygroup/downstream
|
||||
strategy: depend`,
|
||||
},
|
||||
|
||||
RuleInvalidCoverage: {
|
||||
Title: "'coverage:' is not a regex pattern",
|
||||
Severity: Error,
|
||||
Description: "'coverage:' must be a regex pattern wrapped in forward slashes " +
|
||||
"(e.g. '/Coverage: \\d+\\.?\\d*%/'). GitLab uses this pattern to extract " +
|
||||
"the coverage percentage from job output.",
|
||||
Example: `my-job:
|
||||
coverage: "\\d+%" # missing surrounding /…/
|
||||
script: pytest --cov`,
|
||||
Fix: `my-job:
|
||||
coverage: '/Coverage: \d+\.?\d*%/'
|
||||
script: pytest --cov`,
|
||||
},
|
||||
|
||||
RuleInvalidRelease: {
|
||||
Title: "'release:' missing required 'tag_name:'",
|
||||
Severity: Error,
|
||||
Description: "'release:' must be a map and must include a 'tag_name:' key. " +
|
||||
"Without it GitLab cannot create the release.",
|
||||
Example: `release-job:
|
||||
script: echo releasing
|
||||
release:
|
||||
name: My Release # missing tag_name:`,
|
||||
Fix: `release-job:
|
||||
script: echo releasing
|
||||
release:
|
||||
tag_name: $CI_COMMIT_TAG
|
||||
name: My Release`,
|
||||
},
|
||||
|
||||
RuleInvalidEnvironment: {
|
||||
Title: "'environment:' invalid url or action",
|
||||
Severity: Error,
|
||||
Description: "'environment.url' requires 'environment.name' to be set. " +
|
||||
"'environment.action' must be one of: start, stop, prepare, verify, access.",
|
||||
Example: `my-job:
|
||||
script: ./deploy.sh
|
||||
environment:
|
||||
url: https://prod.example.com # name: is required`,
|
||||
Fix: `my-job:
|
||||
script: ./deploy.sh
|
||||
environment:
|
||||
name: production
|
||||
url: https://prod.example.com`,
|
||||
},
|
||||
|
||||
RuleInvalidArtifacts: {
|
||||
Title: "'artifacts:' invalid configuration",
|
||||
Severity: Error,
|
||||
Description: "'artifacts.when' must be on_success, on_failure, or always. " +
|
||||
"'artifacts.expose_as' requires 'artifacts.paths' to be set.",
|
||||
Example: `my-job:
|
||||
script: make
|
||||
artifacts:
|
||||
when: sometimes # invalid value`,
|
||||
Fix: `my-job:
|
||||
script: make
|
||||
artifacts:
|
||||
when: on_failure
|
||||
paths:
|
||||
- build/logs/`,
|
||||
},
|
||||
|
||||
RulePagesPublic: {
|
||||
Title: "pages job missing 'public' in artifacts.paths",
|
||||
Severity: Warning,
|
||||
Description: "The 'pages' job must include 'public' (or a path starting with " +
|
||||
"'public/') in 'artifacts.paths' for GitLab Pages to deploy the site.",
|
||||
Example: `pages:
|
||||
script: hugo
|
||||
artifacts:
|
||||
paths:
|
||||
- dist/ # should include public/`,
|
||||
Fix: `pages:
|
||||
script: hugo --destination public
|
||||
artifacts:
|
||||
paths:
|
||||
- public/`,
|
||||
},
|
||||
|
||||
RuleInvalidCache: {
|
||||
Title: "'cache:' invalid when or policy",
|
||||
Severity: Error,
|
||||
Description: "'cache.when' must be on_success, on_failure, or always. " +
|
||||
"'cache.policy' must be pull, push, or pull-push.",
|
||||
Example: `my-job:
|
||||
script: npm ci
|
||||
cache:
|
||||
paths: [node_modules/]
|
||||
policy: read-only # invalid; use pull`,
|
||||
Fix: `my-job:
|
||||
script: npm ci
|
||||
cache:
|
||||
paths: [node_modules/]
|
||||
policy: pull`,
|
||||
},
|
||||
|
||||
RuleInvalidRulesWhen: {
|
||||
Title: "'rules[n].when:' has invalid value",
|
||||
Severity: Error,
|
||||
Description: "Inside a 'rules:' block, 'when:' must be one of: on_success, " +
|
||||
"on_failure, always, manual, delayed, never. Other values are rejected.",
|
||||
Example: `my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
when: conditional # not valid here
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH
|
||||
when: on_success
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidImage: {
|
||||
Title: "'image:' map form missing 'name:'",
|
||||
Severity: Error,
|
||||
Description: "When 'image:' is a map, it must include a 'name:' key specifying " +
|
||||
"the Docker image. Without it GitLab cannot resolve which image to pull.",
|
||||
Example: `my-job:
|
||||
image:
|
||||
entrypoint: ["/bin/sh"] # missing name:
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
image:
|
||||
name: alpine:3.19
|
||||
entrypoint: ["/bin/sh"]
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleInvalidInherit: {
|
||||
Title: "'inherit.default' or 'inherit.variables' invalid type",
|
||||
Severity: Error,
|
||||
Description: "'inherit.default' and 'inherit.variables' must each be a boolean " +
|
||||
"(true/false) or a list of field/variable names. Other types are rejected.",
|
||||
Example: `my-job:
|
||||
inherit:
|
||||
default: "no" # must be true/false or a list
|
||||
script: echo hi`,
|
||||
Fix: `my-job:
|
||||
inherit:
|
||||
default: false
|
||||
script: echo hi`,
|
||||
},
|
||||
|
||||
RuleNeedsUnknown: {
|
||||
Title: "'needs:' references unknown job",
|
||||
Severity: Error,
|
||||
Description: "A job in the 'needs:' list does not exist in the pipeline. " +
|
||||
"GitLab will refuse to create the pipeline.",
|
||||
Example: `build:
|
||||
stage: build
|
||||
script: make
|
||||
|
||||
test:
|
||||
stage: test
|
||||
needs: [build, lint] # lint does not exist
|
||||
script: make test`,
|
||||
Fix: `lint:
|
||||
stage: build
|
||||
script: make lint
|
||||
|
||||
build:
|
||||
stage: build
|
||||
script: make
|
||||
|
||||
test:
|
||||
stage: test
|
||||
needs: [build, lint]
|
||||
script: make test`,
|
||||
},
|
||||
|
||||
RuleNeedsStageOrder: {
|
||||
Title: "'needs:' job is in a later stage",
|
||||
Severity: Error,
|
||||
Description: "A job listed in 'needs:' is in a later stage than the current " +
|
||||
"job. GitLab does not allow needs: to reference future stages.",
|
||||
Example: `stages: [build, test, deploy]
|
||||
|
||||
test:
|
||||
stage: test
|
||||
needs: [deploy-job] # deploy-job is in a later stage
|
||||
script: make test
|
||||
|
||||
deploy-job:
|
||||
stage: deploy
|
||||
script: ./deploy.sh`,
|
||||
Fix: `stages: [build, test, deploy]
|
||||
|
||||
test:
|
||||
stage: test
|
||||
needs: [build-job]
|
||||
script: make test
|
||||
|
||||
build-job:
|
||||
stage: build
|
||||
script: make`,
|
||||
},
|
||||
|
||||
RuleNeedsCycle: {
|
||||
Title: "circular dependency in 'needs:' graph",
|
||||
Severity: Error,
|
||||
Description: "Two or more jobs in the 'needs:' graph form a cycle — A needs B " +
|
||||
"and B needs A (directly or transitively). GitLab will reject the pipeline.",
|
||||
Example: `job-a:
|
||||
stage: test
|
||||
needs: [job-b]
|
||||
script: echo a
|
||||
|
||||
job-b:
|
||||
stage: test
|
||||
needs: [job-a]
|
||||
script: echo b`,
|
||||
Fix: `job-a:
|
||||
stage: test
|
||||
script: echo a
|
||||
|
||||
job-b:
|
||||
stage: test
|
||||
needs: [job-a]
|
||||
script: echo b`,
|
||||
},
|
||||
|
||||
RuleUnknownDependency: {
|
||||
Title: "'dependencies:' references unknown job",
|
||||
Severity: Error,
|
||||
Description: "A job listed in 'dependencies:' does not exist in the pipeline. " +
|
||||
"GitLab will refuse to create the pipeline.",
|
||||
Example: `test:
|
||||
stage: test
|
||||
dependencies: [build, missing-job]
|
||||
script: make test`,
|
||||
Fix: `build:
|
||||
stage: build
|
||||
script: make
|
||||
artifacts:
|
||||
paths: [dist/]
|
||||
|
||||
test:
|
||||
stage: test
|
||||
dependencies: [build]
|
||||
script: make test`,
|
||||
},
|
||||
|
||||
RuleDependencyStage: {
|
||||
Title: "'dependencies:' job in same or later stage",
|
||||
Severity: Error,
|
||||
Description: "'dependencies:' can only reference jobs in earlier stages. " +
|
||||
"Referencing a job in the same or a later stage is not allowed because " +
|
||||
"artifacts would not yet be available.",
|
||||
Example: `stages: [test, deploy]
|
||||
|
||||
test:
|
||||
stage: test
|
||||
dependencies: [deploy-job] # deploy is a later stage
|
||||
script: make test
|
||||
|
||||
deploy-job:
|
||||
stage: deploy
|
||||
script: ./deploy.sh`,
|
||||
Fix: `stages: [build, test, deploy]
|
||||
|
||||
build:
|
||||
stage: build
|
||||
script: make
|
||||
artifacts:
|
||||
paths: [dist/]
|
||||
|
||||
test:
|
||||
stage: test
|
||||
dependencies: [build]
|
||||
script: make test`,
|
||||
},
|
||||
|
||||
RuleUndeclaredVariable: {
|
||||
Title: "'rules:if:' references undeclared variable",
|
||||
Severity: Warning,
|
||||
Description: "A 'rules:if:' expression references a variable that is not " +
|
||||
"declared in any 'variables:' block in the pipeline YAML. This may be a " +
|
||||
"typo, or the variable may be set in GitLab project settings (invisible to " +
|
||||
"glint). Predefined CI_* and GITLAB_* variables are always exempt.",
|
||||
Example: `variables:
|
||||
APP_ENV: staging
|
||||
|
||||
my-job:
|
||||
rules:
|
||||
- if: $DEPLOY_ENV == "prod" # DEPLOY_ENV not declared
|
||||
script: ./deploy.sh`,
|
||||
Fix: `variables:
|
||||
APP_ENV: staging
|
||||
DEPLOY_ENV: staging # declare it, or set it in GitLab project settings
|
||||
|
||||
my-job:
|
||||
rules:
|
||||
- if: $DEPLOY_ENV == "prod"
|
||||
script: ./deploy.sh`,
|
||||
},
|
||||
|
||||
RuleDeadRules: {
|
||||
Title: "rules: block has all 'when: never' — job permanently excluded",
|
||||
Severity: Warning,
|
||||
Description: "Every rule in the job's 'rules:' block has an explicit " +
|
||||
"'when: never'. No matter which conditions match, the job will never " +
|
||||
"be included in any pipeline run.",
|
||||
Example: `my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == "main"
|
||||
when: never
|
||||
- when: never
|
||||
script: echo unreachable`,
|
||||
Fix: `# Option 1: remove the job entirely
|
||||
# Option 2: give at least one rule a non-never when:
|
||||
my-job:
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == "main"
|
||||
when: on_success
|
||||
- when: never
|
||||
script: echo deploy`,
|
||||
},
|
||||
|
||||
RuleInvalidService: {
|
||||
Title: "'services:' map form missing 'name:' or invalid 'alias:'",
|
||||
Severity: Error,
|
||||
Description: "When a service entry is a map it must include a 'name:' key. " +
|
||||
"'alias:' (if set) must be a valid DNS label: alphanumeric characters, " +
|
||||
"hyphens, and dots only; must start and end with alphanumeric.",
|
||||
Example: `my-job:
|
||||
script: pytest
|
||||
services:
|
||||
- alias: my_db # underscore is not valid in a DNS label`,
|
||||
Fix: `my-job:
|
||||
script: pytest
|
||||
services:
|
||||
- name: postgres:15
|
||||
alias: my-db`,
|
||||
},
|
||||
|
||||
RuleAbsoluteGlobPath: {
|
||||
Title: "'rules:changes' or 'rules:exists' uses absolute path",
|
||||
Severity: Warning,
|
||||
Description: "Paths in 'rules:changes' and 'rules:exists' are always relative " +
|
||||
"to the repository root. An absolute path starting with '/' will never " +
|
||||
"match any file and will silently disable the rule.",
|
||||
Example: `my-job:
|
||||
rules:
|
||||
- changes:
|
||||
- /src/**/*.go # absolute — will never match
|
||||
script: make`,
|
||||
Fix: `my-job:
|
||||
rules:
|
||||
- changes:
|
||||
- src/**/*.go
|
||||
script: make`,
|
||||
},
|
||||
|
||||
RuleInvalidTimeout: {
|
||||
Title: "'timeout:' is not a valid duration string",
|
||||
Severity: Error,
|
||||
Description: "'timeout:' must be a GitLab CI duration string composed of " +
|
||||
"recognised time units: weeks (w), days (d), hours (h), minutes (m/min), " +
|
||||
"seconds (s). Examples: '1h 30m', '90 minutes', '2 hours'.",
|
||||
Example: `my-job:
|
||||
timeout: "1:30:00" # colon-separated format not supported
|
||||
script: long-running-task.sh`,
|
||||
Fix: `my-job:
|
||||
timeout: 1h 30m
|
||||
script: long-running-task.sh`,
|
||||
},
|
||||
|
||||
RuleInvalidIDToken: {
|
||||
Title: "'id_tokens:' entry missing required 'aud:' key",
|
||||
Severity: Error,
|
||||
Description: "Each entry under 'id_tokens:' must be a map with an 'aud:' " +
|
||||
"(audience) key. Without 'aud:' GitLab cannot generate the ID token " +
|
||||
"and the job will fail.",
|
||||
Example: `my-job:
|
||||
id_tokens:
|
||||
MY_TOKEN:
|
||||
# missing aud:
|
||||
script: vault-login.sh`,
|
||||
Fix: `my-job:
|
||||
id_tokens:
|
||||
MY_TOKEN:
|
||||
aud: https://vault.example.com
|
||||
script: vault-login.sh`,
|
||||
},
|
||||
|
||||
RuleInvalidSecret: {
|
||||
Title: "'secrets:' entry missing a provider key",
|
||||
Severity: Error,
|
||||
Description: "Each entry under 'secrets:' must specify a provider: one of " +
|
||||
"'vault:', 'gcp_secret_manager:', or 'azure_key_vault:'. Without a " +
|
||||
"provider GitLab cannot retrieve the secret.",
|
||||
Example: `my-job:
|
||||
secrets:
|
||||
DB_PASSWORD:
|
||||
path: secret/db/password # no provider key
|
||||
script: run.sh`,
|
||||
Fix: `my-job:
|
||||
secrets:
|
||||
DB_PASSWORD:
|
||||
vault:
|
||||
engine:
|
||||
name: kv-v2
|
||||
path: secret
|
||||
path: db/password
|
||||
field: password
|
||||
script: run.sh`,
|
||||
},
|
||||
|
||||
RulePagesPublish: {
|
||||
Title: "'pages:' keyword publish directory missing from 'artifacts.paths'",
|
||||
Severity: Warning,
|
||||
Description: "A job using the 'pages:' keyword must include its publish " +
|
||||
"directory in 'artifacts.paths'. Without this, GitLab Pages will not " +
|
||||
"deploy the site.",
|
||||
Example: `my-pages-job:
|
||||
script: hugo
|
||||
pages:
|
||||
publish: public
|
||||
artifacts:
|
||||
paths:
|
||||
- dist/ # missing public/`,
|
||||
Fix: `my-pages-job:
|
||||
script: hugo
|
||||
pages:
|
||||
publish: public
|
||||
artifacts:
|
||||
paths:
|
||||
- public/`,
|
||||
},
|
||||
|
||||
RuleDuplicateStage: {
|
||||
Title: "duplicate stage name in 'stages:'",
|
||||
Severity: Warning,
|
||||
Description: "A stage name appears more than once in the 'stages:' list. " +
|
||||
"GitLab silently merges duplicate stage entries, which can make the " +
|
||||
"pipeline order confusing.",
|
||||
Example: `stages:
|
||||
- build
|
||||
- test
|
||||
- test # duplicate`,
|
||||
Fix: `stages:
|
||||
- build
|
||||
- test`,
|
||||
},
|
||||
|
||||
RuleInvalidCacheKeyFiles: {
|
||||
Title: "'cache.key.files' contains a glob pattern",
|
||||
Severity: Warning,
|
||||
Description: "'cache.key.files' must be a list of exact file paths. Glob " +
|
||||
"patterns (*, ?, [...]) are not expanded — the literal glob string is " +
|
||||
"used as the cache key, which probably doesn't match your intent.",
|
||||
Example: `my-job:
|
||||
script: npm ci
|
||||
cache:
|
||||
key:
|
||||
files:
|
||||
- package*.json # glob — use exact path`,
|
||||
Fix: `my-job:
|
||||
script: npm ci
|
||||
cache:
|
||||
key:
|
||||
files:
|
||||
- package.json
|
||||
- package-lock.json`,
|
||||
},
|
||||
|
||||
RuleStaticDeadRules: {
|
||||
Title: "rules:if: block statically never activates",
|
||||
Severity: Warning,
|
||||
Description: "Every 'rules:if:' condition in this job evaluates to false " +
|
||||
"using the variable values declared in the pipeline YAML. The job will " +
|
||||
"never be included in any pipeline run. This check only fires when ALL " +
|
||||
"referenced variables are declared in the YAML (predefined CI_* variables " +
|
||||
"are not evaluated to avoid false positives).",
|
||||
Example: `variables:
|
||||
ENABLE_DEPLOY: "false"
|
||||
|
||||
deploy:
|
||||
rules:
|
||||
- if: '$ENABLE_DEPLOY == "true"' # always false: ENABLE_DEPLOY is "false"
|
||||
script: ./deploy.sh`,
|
||||
Fix: `variables:
|
||||
ENABLE_DEPLOY: "true" # fix the variable value
|
||||
|
||||
deploy:
|
||||
rules:
|
||||
- if: '$ENABLE_DEPLOY == "true"'
|
||||
script: ./deploy.sh
|
||||
|
||||
# Or add an unconditional fallback:
|
||||
deploy:
|
||||
rules:
|
||||
- if: '$ENABLE_DEPLOY == "true"'
|
||||
- when: manual # allow manual trigger as a fallback
|
||||
script: ./deploy.sh`,
|
||||
},
|
||||
|
||||
RuleInheritNoDefault: {
|
||||
Title: "'inherit: default:' declared but no 'default:' block",
|
||||
Severity: Warning,
|
||||
Description: "A job declares 'inherit: default:' but the pipeline has no " +
|
||||
"'default:' block, so the declaration has no effect. This can also fire " +
|
||||
"when 'inherit: default: [list]' names fields that are not set in the " +
|
||||
"'default:' block.",
|
||||
Example: `# No default: block exists
|
||||
|
||||
my-job:
|
||||
inherit:
|
||||
default: false # no-op: nothing to opt out of
|
||||
script: echo hi`,
|
||||
Fix: `# Either add a default: block...
|
||||
default:
|
||||
before_script:
|
||||
- source venv/bin/activate
|
||||
|
||||
my-job:
|
||||
inherit:
|
||||
default: false
|
||||
script: echo hi
|
||||
|
||||
# ...or remove the pointless inherit: declaration
|
||||
my-job:
|
||||
script: echo hi`,
|
||||
},
|
||||
}
|
||||
Reference in New Issue
Block a user