@intentius/chant-lexicon-gitlab 0.0.8 → 0.0.10

package/dist/skills/chant-gitlab.md

@@ -4,56 +4,499 @@ description: Build, validate, and deploy GitLab CI pipelines from a chant projec
 user-invocable: true
 ---
 
-# Deploying GitLab CI Pipelines from Chant
+# GitLab CI/CD Operational Playbook
 
-This project defines GitLab CI jobs as TypeScript in `src/`. Use these steps to build, validate, and deploy.
+## How chant and GitLab CI relate
 
-## Build the pipeline
+chant is a **synthesis-only** tool — it compiles TypeScript source files into `.gitlab-ci.yml` (YAML). chant does NOT call GitLab APIs. Your job as an agent is to bridge the two:
+
+- Use **chant** for: build, lint, diff (local YAML comparison)
+- Use **git + GitLab API** for: push, merge requests, pipeline monitoring, job logs, rollback, and all deployment operations
+
+The source of truth for pipeline configuration is the TypeScript in `src/`. The generated `.gitlab-ci.yml` is an intermediate artifact — never edit it by hand.
+
+## Scaffolding a new project
+
+### Initialize with a template
+
+```bash
+chant init --lexicon gitlab                           # default: config.ts + pipeline.ts
+chant init --lexicon gitlab --template node-pipeline   # NodePipeline composite
+chant init --lexicon gitlab --template python-pipeline # PythonPipeline composite
+chant init --lexicon gitlab --template docker-build    # DockerBuild composite
+chant init --lexicon gitlab --template review-app      # ReviewApp composite
+```
+
+This creates `src/` with chant pipeline definitions. It does NOT create application files — you bring your own app code.
+
+### Available templates
+
+| Template | What it generates | Best for |
+|----------|-------------------|----------|
+| *(default)* | `config.ts` + `pipeline.ts` with build/test jobs | Custom pipelines from scratch |
+| `node-pipeline` | `NodePipeline` composite with npm install/build/test | Node.js apps |
+| `python-pipeline` | `PythonPipeline` composite with venv/pytest | Python apps |
+| `docker-build` | `DockerBuild` composite + test job | Containerized apps |
+| `review-app` | `ReviewApp` composite + test job | Apps needing per-MR environments |
+
+## Deploying to GitLab
+
+### What goes in the GitLab repo
+
+The GitLab repo needs TWO things:
+1. **`.gitlab-ci.yml`** — generated by `chant build`
+2. **Your application files** — whatever the pipeline scripts reference
+
+chant only generates the YAML. Application files (`package.json`, `Dockerfile`, `requirements.txt`, source code, tests) are your responsibility.
+
+### Typical project structure in the GitLab repo
+
+**Node.js project:**
+```
+.gitlab-ci.yml      # generated by chant
+package.json         # your app's package.json with build/test scripts
+index.js             # your app code
+test.js              # your tests
+```
+
+**Python project:**
+```
+.gitlab-ci.yml
+requirements.txt     # must include pytest, pytest-cov if using PythonPipeline defaults
+app.py
+test_app.py
+```
+
+**Docker project:**
+```
+.gitlab-ci.yml
+Dockerfile
+src/                 # your app source
+```
+
+### Important: npm ci vs npm install
+
+The `NodePipeline` composite defaults to `npm ci`, which requires a `package-lock.json` in the repo. If your repo does not have a lockfile, override with:
+
+```typescript
+NodePipeline({
+  installCommand: "npm install",  // use instead of npm ci
+  ...
+})
+```
+
+Or generate a lockfile: `npm install && git add package-lock.json`.
+
+### Step-by-step: push to GitLab
+
+```bash
+# 1. Build the YAML from chant source
+chant build src/ --output .gitlab-ci.yml
+
+# 2. Initialize git (if needed) and commit everything
+git init -b main
+git add .gitlab-ci.yml package.json index.js test.js  # add your app files
+git commit -m "Initial pipeline"
+
+# 3. Push to GitLab
+git remote add origin git@gitlab.com:YOUR_GROUP/YOUR_PROJECT.git
+git push -u origin main
+```
+
+The pipeline triggers automatically on push. Do NOT commit the chant `src/` directory, `node_modules/`, or `.chant/` to the GitLab repo — those are local development files.
+
+## Build and validate
+
+### Build the pipeline
 
 ```bash
 chant build src/ --output .gitlab-ci.yml
 ```
 
-## Validate before pushing
+Options:
+- `--format yaml` — emit YAML (default for GitLab)
+- `--watch` — rebuild on source changes
+- `--output <path>` — write to a specific file
+
+### Lint the source
 
 ```bash
 chant lint src/
 ```
 
-For API-level validation against your GitLab instance:
+Options:
+- `--fix` — auto-fix violations where possible
+- `--format sarif` — SARIF output for CI integration
+- `--watch` — re-lint on changes
+
+### Validate with GitLab CI Lint API
+
 ```bash
 curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
-  "https://gitlab.com/api/v4/ci/lint" \
-  --data "{\"content\": \"$(cat .gitlab-ci.yml)\"}"
+  --header "Content-Type: application/json" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/ci/lint" \
+  --data-binary @- <<EOF
+{"content": $(cat .gitlab-ci.yml | jq -Rs .)}
+EOF
 ```
 
-## Deploy
+Add `"dry_run": true, "include_merged_yaml": true` for full expansion with includes resolved.
+
+### What each step catches
+
+| Step | Catches | When to run |
+|------|---------|-------------|
+| `chant lint` | Deprecated only/except (WGL001), missing script (WGL002), missing stage (WGL003), artifacts without expiry (WGL004) | Every edit |
+| `chant build` | Post-synth checks: undefined stages (WGL010), unreachable jobs (WGL011), deprecated properties (WGL012), invalid needs targets (WGL013), invalid extends targets (WGL014), circular needs chains (WGL015) | Before push |
+| CI Lint API | GitLab-specific validation: include resolution, variable expansion, YAML schema errors | Before merge to default branch |
+
+Always run all three before deploying. Lint catches things the API cannot (and vice versa).
 
-Commit and push the generated `.gitlab-ci.yml` — GitLab runs the pipeline automatically:
+## Diffing and change preview
+
+### Local diff
+
+Compare generated `.gitlab-ci.yml` against the version on the remote branch:
 
 ```bash
+# Build the proposed config
 chant build src/ --output .gitlab-ci.yml
-git add .gitlab-ci.yml
-git commit -m "Update pipeline"
-git push
+
+# Diff against the remote version
+git diff origin/main -- .gitlab-ci.yml
+```
+
+### MR pipeline preview
+
+Push to a branch and open a merge request — GitLab shows the pipeline that would run without executing it. This is the safest way to preview pipeline changes for production.
+
+### CI Lint API with dry run
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/ci/lint" \
+  --data-binary @- <<EOF
+{"content": $(cat .gitlab-ci.yml | jq -Rs .), "dry_run": true, "include_merged_yaml": true}
+EOF
+```
+
+This resolves all `include:` directives and expands the full pipeline — useful for catching issues with cross-file references.
+
+### Safe preview checklist
+
+Before merging pipeline changes, verify:
+1. All jobs have valid `stage:` values and stages are defined
+2. `needs:` references point to existing job names
+3. `rules:` conditions match the intended branches/events
+4. Environment names and `on_stop` references are correct
+5. Docker images are accessible from your runners
+6. Secrets/variables referenced in scripts exist in project settings
+
+## Deploying pipeline changes
+
+### Safe path (production pipelines)
+
+1. Build: `chant build src/ --output .gitlab-ci.yml`
+2. Lint: `chant lint src/`
+3. Validate: CI Lint API (see above)
+4. Push to feature branch: `git push -u origin feature/pipeline-update`
+5. Open MR — review pipeline diff in the MR widget
+6. Merge — pipeline runs on the default branch
+
+### Fast path (dev/iteration)
+
+```bash
+chant build src/ --output .gitlab-ci.yml
+git add .gitlab-ci.yml && git commit -m "Update pipeline" && git push
+```
+
+### Which path to use
+
+| Scenario | Path |
+|----------|------|
+| Production pipeline with deploy jobs | Safe path (MR review) |
+| Pipeline with environment/secrets changes | Safe path (MR review) |
+| Dev/test pipeline iteration | Fast path (direct push) |
+| CI/CD with approval gates or protected environments | Safe path + protected branch |
+
+## Environment lifecycle
+
+Environments are created by jobs with an `environment:` keyword. They track deployments and enable rollback.
+
+### Review apps pattern
+
+Deploy on MR, auto-stop when MR is merged or closed:
+
+```typescript
+new Job({
+  stage: "deploy",
+  environment: new Environment({
+    name: "review/$CI_COMMIT_REF_SLUG",
+    url: "https://$CI_COMMIT_REF_SLUG.example.com",
+    onStop: "stop_review",
+    autoStopIn: "1 week",
+  }),
+  script: ["./deploy-review.sh"],
+  rules: [{ if: "$CI_MERGE_REQUEST_IID" }],
+});
+```
+
+### Environment promotion
+
+Deploy through environments in order: dev → staging → production. Use `rules:` and `when: manual` to gate promotions.
+
+### Rollback to a previous deployment
+
+```bash
+# List deployments for an environment
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/environments/$ENV_ID/deployments?order_by=created_at&sort=desc&per_page=5"
+
+# Re-deploy a previous deployment's commit
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/deployments" \
+  --data "environment=production&sha=$PREVIOUS_SHA&ref=main&tag=false&status=created"
 ```
 
-## Check pipeline status
+Alternatively, revert the MR that introduced the change and let the pipeline re-run.
 
-- GitLab UI: project → CI/CD → Pipelines
-- API: `curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines?per_page=5"`
+## Pipeline and job states
 
-## Retry a failed job
+### Pipeline states
 
-- GitLab UI: click Retry on the failed job
-- API: `curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/retry"`
+| State | Meaning | Action |
+|-------|---------|--------|
+| `created` | Pipeline created, not yet started | Wait |
+| `waiting_for_resource` | Waiting for runner | Check runner availability |
+| `preparing` | Job is being prepared | Wait |
+| `pending` | Waiting for runner to pick up | Check runner tags/availability |
+| `running` | Pipeline is executing | Monitor |
+| `success` | All jobs passed | None — healthy |
+| `failed` | One or more jobs failed | Check failed job logs |
+| `canceled` | Pipeline was canceled | Re-run if needed |
+| `skipped` | Pipeline was skipped by rules | Check rules configuration |
+| `manual` | Pipeline waiting for manual action | Trigger manual job or cancel |
+| `scheduled` | Waiting for scheduled time | Wait |
 
-## Cancel a running pipeline
+### Job states
 
-- API: `curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/cancel"`
+| State | Meaning | Action |
+|-------|---------|--------|
+| `created` | Job created | Wait |
+| `pending` | Waiting for runner | Check runner tags |
+| `running` | Job executing | Monitor logs |
+| `success` | Job passed | None |
+| `failed` | Job failed | Read trace log |
+| `canceled` | Job canceled | Re-run if needed |
+| `skipped` | Job skipped by rules/needs | Check rules |
+| `manual` | Waiting for manual trigger | Play or skip |
+| `allowed_failure` | Failed but allowed | Review — may indicate flaky test |
 
-## Troubleshooting
+## Monitoring pipelines
+
+### Check pipeline status
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID"
+```
 
-- Check job logs in GitLab UI: project → CI/CD → Jobs → click the job
-- `chant lint src/` catches: missing scripts (WGL002), deprecated only/except (WGL001), missing stages (WGL003), artifacts without expiry (WGL004)
-- Post-synth checks (WGL010, WGL011) run during build
+### List recent pipelines for a branch
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines?ref=main&per_page=5"
+```
+
+### Get jobs in a pipeline
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs"
+```
+
+### Stream job logs
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/trace"
+```
+
+### Download job artifacts
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --output artifacts.zip \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/artifacts"
+```
+
+## Merge request pipeline workflow
+
+### How MR pipelines differ
+
+MR pipelines run in a merge request context with `CI_MERGE_REQUEST_IID` available. Branch pipelines run on push with `CI_COMMIT_BRANCH`. A job cannot have both — use `rules:` to target one or the other.
+
+### Common rules patterns
+
+```yaml
+# Run only on MR pipelines
+rules:
+  - if: $CI_MERGE_REQUEST_IID
+
+# Run only on the default branch
+rules:
+  - if: $CI_COMMIT_BRANCH == "main"
+
+# Run on MRs and the default branch (but not both at once)
+rules:
+  - if: $CI_MERGE_REQUEST_IID
+  - if: $CI_COMMIT_BRANCH == "main"
+```
+
+### Merged results pipelines
+
+Enable in project settings → CI/CD → General pipelines → "Merged results pipelines". These test the result of merging your branch into the target — catching integration issues before merge.
+
+### Merge trains
+
+Merge trains queue MRs and test each one merged on top of the previous. Enable in project settings → Merge requests → "Merge trains". Requires merged results pipelines.
+
+## Troubleshooting decision tree
+
+### Step 1: Check pipeline status
+
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID" | jq '.status'
+```
+
+### Step 2: Branch on status
+
+- **`running` / `pending` / `created`** → Wait. Do not take action while the pipeline is in progress.
+- **`failed`** → Read the failed job logs (Step 3).
+- **`success`** → Pipeline is healthy. If behavior is wrong, check job scripts and configuration.
+- **`canceled`** → Re-run if needed: `curl --request POST ... /pipelines/$PIPELINE_ID/retry`
+- **`skipped`** → All jobs were filtered out by `rules:`. Check rule conditions.
+
+### Step 3: Read failed job logs
+
+```bash
+# Get failed jobs
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs?scope=failed" | jq '.[].id'
+
+# Read the trace for a failed job
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/trace"
+```
+
+### Step 4: Diagnose by error pattern
+
+| Error pattern | Likely cause | Fix |
+|---------------|-------------|-----|
+| "no matching runner" | No runner with matching tags | Check runner tags, register a runner |
+| "image pull failed" | Docker image not found or auth failed | Check image name, registry credentials |
+| "script exit code 1" | Script command failed | Read job log for the failing command |
+| "artifact upload failed" | Artifact path doesn't exist or too large | Check `artifacts.paths`, size limits |
+| "cache not found" | Cache key mismatch or first run | Expected on first run; check `cache.key` |
+| "yaml invalid" | Syntax error in generated YAML | Run `chant lint src/` and CI Lint API |
+| "pipeline filtered out" | All jobs filtered by rules | Check `rules:` conditions |
+| "job timed out" | Job exceeded timeout | Increase `timeout:` or optimize job |
+| "stuck or pending" | No available runner | Check runner status, tags, executor capacity |
+| "environment does not exist" | `on_stop` references non-existent job | Check `on_stop` job name matches expanded name |
+| "needs job not found" | `needs:` references non-existent job | Check job names, stage ordering |
+
+## Variable management
+
+### Variable types and precedence
+
+Variables are resolved in this order (highest priority first):
+1. Job-level `variables:`
+2. Project CI/CD variables (Settings → CI/CD → Variables)
+3. Group CI/CD variables
+4. Instance CI/CD variables
+
+### Protected and masked variables
+
+- **Protected**: only available in pipelines on protected branches/tags
+- **Masked**: hidden in job logs (value must meet masking requirements)
+
+### Managing variables via API
+
+```bash
+# List project variables
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/variables"
+
+# Create a variable
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/variables" \
+  --form "key=DEPLOY_TOKEN" --form "value=secret" --form "masked=true" --form "protected=true"
+
+# Update a variable
+curl --request PUT --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/variables/DEPLOY_TOKEN" \
+  --form "value=new-secret"
+
+# Delete a variable
+curl --request DELETE --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/variables/DEPLOY_TOKEN"
+```
+
+## Quick reference
+
+### Pipeline info commands
+
+```bash
+# List recent pipelines
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines?per_page=5"
+
+# Get pipeline status
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID"
+
+# Get jobs in a pipeline
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs"
+
+# Read job log
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/trace"
+
+# Retry a failed pipeline
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/retry"
+
+# Cancel a running pipeline
+curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/cancel"
+```
+
+### Full build-to-deploy pipeline
+
+```bash
+# 1. Lint
+chant lint src/
+
+# 2. Build
+chant build src/ --output .gitlab-ci.yml
+
+# 3. Validate via API
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --header "Content-Type: application/json" \
+  "https://gitlab.com/api/v4/projects/$PROJECT_ID/ci/lint" \
+  --data-binary @- <<EOF
+{"content": $(cat .gitlab-ci.yml | jq -Rs .)}
+EOF
+
+# 4. Push to feature branch
+git checkout -b feature/pipeline-update
+git add .gitlab-ci.yml
+git commit -m "Update pipeline"
+git push -u origin feature/pipeline-update
+
+# 5. Open MR, review pipeline diff, merge
+# Pipeline runs automatically on the default branch after merge
+```

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@
 
 export declare class AllowFailure {
   constructor(props: {
-    exit_codes: number;
+    exit_codes: number | number[];
   });
 }
 
@@ -48,7 +48,7 @@ export declare class Default {
     before_script?: string | string[];
     cache?: Cache | Cache[];
     hooks?: Record<string, unknown>;
-    id_tokens?: Record<string, unknown>;
+    id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
     image?: Image;
     interruptible?: boolean;
@@ -85,19 +85,34 @@ export declare class Image {
     docker?: Record<string, unknown>;
     /** Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array. */
     entrypoint?: any[];
-    pull_policy?: "always" | "never" | "if-not-present" | "always" | "never" | "if-not-present"[];
+    pull_policy?: "always" | "never" | "if-not-present" | ("always" | "never" | "if-not-present")[];
   });
 }
 
 export declare class Include {
   constructor(props: {
-    file: string | string[];
-    /** Path to the project, e.g. `group/project`, or `group/sub-group/project` [Learn more](https://docs.gitlab.com/ee/ci/yaml/index.html#includefile). */
-    project: string;
+    /** Local path to component directory or full path to external component directory. */
+    component?: string;
+    file?: string | string[];
     inputs?: Record<string, unknown>;
+    /** Relative path from local repository root (`/`) to the `yaml`/`yml` file template. The file must be on the same branch, and does not work across git submodules. */
+    local?: string;
+    /** Path to the project, e.g. `group/project`, or `group/sub-group/project` [Learn more](https://docs.gitlab.com/ee/ci/yaml/index.html#includefile). */
+    project?: string;
     /** Branch/Tag/Commit-hash for the target project. */
     ref?: string;
+    /** URL to a `yaml`/`yml` template file using HTTP/HTTPS. */
+    remote?: string;
     rules?: any[];
+    /** Use a `.gitlab-ci.yml` template as a base, e.g. `Nodejs.gitlab-ci.yml`. */
+    template?: string;
+  });
+}
+
+export declare class Inherit {
+  constructor(props: {
+    default?: boolean | ("after_script" | "artifacts" | "before_script" | "cache" | "image" | "interruptible" | "retry" | "services" | "tags" | "timeout")[];
+    variables?: boolean | string[];
   });
 }
 
@@ -113,20 +128,20 @@ export declare class Job {
     /** Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts. */
     dependencies?: string[];
     /** Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project. */
-    environment?: string | Record<string, any>;
+    environment?: Environment | string;
     /** Job will run *except* for when these filtering options match. */
     except?: any;
     /** The name of one or more jobs to inherit configuration from. */
     extends?: string | string[];
     hooks?: Record<string, unknown>;
-    id_tokens?: Record<string, unknown>;
+    id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
     image?: Image;
-    inherit?: Record<string, unknown>;
+    inherit?: Inherit;
     interruptible?: boolean;
     manual_confirmation?: string;
     /** The list of jobs in previous stages whose sole completion is needed to start the current job. */
-    needs?: string | Record<string, any> | any[][];
+    needs?: Need[];
     /** Job will run *only* when these filtering options match. */
     only?: any;
     pages?: Record<string, any> | boolean;
@@ -134,7 +149,7 @@ export declare class Job {
     /** A path to a directory that contains the files to be published with Pages */
     publish?: string;
     /** Indicates that the job creates a Release. */
-    release?: Record<string, unknown>;
+    release?: Release;
     /** Limit job concurrency. Can be used to ensure that the Runner will not run certain jobs simultaneously. */
     resource_group?: string;
     retry?: Retry | number;
@@ -148,12 +163,24 @@ export declare class Job {
     start_in?: string;
     tags?: any[];
     timeout?: string;
-    trigger?: Record<string, any> | string;
+    trigger?: Trigger | string;
     variables?: Record<string, unknown>;
     when?: "on_success" | "on_failure" | "always" | "never" | "manual" | "delayed";
   });
 }
 
+export declare class Need {
+  constructor(props: {
+    job: string;
+    artifacts?: boolean;
+    optional?: boolean;
+    parallel?: any;
+    pipeline?: string;
+    project?: string;
+    ref?: string;
+  });
+}
+
 export declare class Parallel {
   constructor(props: {
     /** Defines different variables for jobs that are running in parallel. */
@@ -211,19 +238,20 @@ export declare class Service {
     command?: string[];
     docker?: Record<string, unknown>;
     entrypoint?: string[];
-    pull_policy?: "always" | "never" | "if-not-present" | "always" | "never" | "if-not-present"[];
+    pull_policy?: "always" | "never" | "if-not-present" | ("always" | "never" | "if-not-present")[];
     variables?: Record<string, unknown>;
   });
 }
 
 export declare class Trigger {
   constructor(props: {
-    /** Path to the project, e.g. `group/project`, or `group/sub-group/project`. */
-    project: string;
     /** The branch name that a downstream pipeline will use */
     branch?: string;
     /** Specify what to forward to the downstream pipeline. */
     forward?: Record<string, unknown>;
+    include?: string | Record<string, any>[];
+    /** Path to the project, e.g. `group/project`, or `group/sub-group/project`. */
+    project?: string;
     /** You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend */
     strategy?: "depend";
   });
@@ -233,7 +261,18 @@ export declare class Workflow {
   constructor(props: {
     auto_cancel?: AutoCancel;
     name?: string;
-    rules?: Record<string, any> | string[][];
+    rules?: WorkflowRule[];
+  });
+}
+
+export declare class WorkflowRule {
+  constructor(props: {
+    auto_cancel?: AutoCancel;
+    changes?: any;
+    exists?: any;
+    if?: string;
+    variables?: Record<string, unknown>;
+    when?: "always" | "never";
   });
 }