Guide · Intermediate · 20-minute read · Updated 8 November 2026

A GitLab Issue Queue for Coding Agents: Selection Rules, Checks, and Stop Conditions

Очередь GitLab-задач для coding agent: правила выбора, проверки и остановки
Temporary fallback cover; replace in editorial pass.

A coding agent should not treat a GitLab issue list as an invitation to improvise. A safe queue gives the agent a narrow selection rule, repository-specific instructions, repeatable checks, and an explicit point where it must stop and ask a human.

This article describes a reproducible workflow for repositories where an agent may inspect issues, prepare a scoped change, run local verification, and open a merge request. It does not assume a particular programming language, runner, hosting plan, or automation product. Commands are examples; adapt them to the repository and label them as examples in your own documentation.

The operating model

The queue is a controlled handoff between GitLab and the repository. GitLab provides issue state, labels, ownership, and the merge-request review path. The repository provides instructions, tests, formatting rules, and the definition of a valid change. The agent connects the two, but it must not replace human decisions about product intent, security, data handling, or release risk.

A useful model is:

  1. Select exactly one eligible issue.
  2. Confirm that the issue is actionable and within the agent’s authority.
  3. Read repository instructions before editing.
  4. Make the smallest change that satisfies the acceptance criteria.
  5. Run the checks required by the repository.
  6. Report evidence, limitations, and remaining uncertainty.
  7. Stop for human review when a stop condition is met.

The important property is not that every task is automated. It is that every transition is observable and reversible.

1. Define an eligible issue

Do not let the agent choose “the next interesting issue.” Define eligibility as a conjunction of rules. A queue item is eligible only when every required condition is true.

eligible(issue) =
  issue.state == "opened"
  AND issue.labels contains "agent-ready"
  AND issue.labels contains "size:small"
  AND issue.assignee is empty
  AND issue.milestone is current
  AND issue has acceptance criteria
  AND issue has no "human-only" label
  AND issue has no unresolved blocking dependency

The exact field names depend on your GitLab process. The principle is stable: selection should be deterministic enough that two operators looking at the same queue can explain why the same issue was selected.

Recommended labels

Use labels to communicate authority and risk, not just topic.

Labels are coordination signals, not security boundaries. A label can be changed incorrectly, and an agent should not infer permission to access secrets, production systems, or personal data from the presence of agent-ready.

Preventing duplicate work

The first write operation should claim the issue. A simple claim protocol is:

  1. Read the issue and record its current state, labels, assignee, and last update.
  2. Re-read immediately before claiming it.
  3. Add agent-in-progress and assign the issue to the designated bot or service account.
  4. Write a short comment containing the claim time, intended scope, and worker identifier.
  5. Abort if the issue changed between the two reads.

If the integration cannot make the claim atomically, treat the claim as advisory. The merge request and repository checks must still protect against conflicting work.

2. Make the issue actionable

An agent-ready issue should answer five questions:

A practical issue template can make these answers mandatory:

## Goal
Describe one observable outcome.

## Acceptance criteria
- [ ] ...
- [ ] ...

## Scope
List the expected files, module, endpoint, or user flow.

## Verification
Name the test, command, or manual check that proves the change.

## Out of scope
List adjacent behavior that must remain unchanged.

## Human decisions
List decisions the agent must stop for rather than infer.

“Fix the API” is not an acceptance criterion. “Return a validation error when the required field is absent, preserve the existing response for valid requests, and add a regression test” is closer to an executable specification.

3. Put repository instructions where the agent can find them

Repository instructions should be versioned with the code. A common arrangement is a root-level AGENTS.md, with more specific instruction files in subdirectories when the repository needs them.

For example:

repository/
├── AGENTS.md
├── .gitlab-ci.yml
├── docs/
│   └── AGENTS.md
├── services/
│   └── payments/
│       └── AGENTS.md
└── src/

The root file should state the universal rules. A nested file should narrow or extend them for its directory. Avoid instructions that depend on unstated local knowledge.

Example root instructions

# Repository instructions

## Before editing
- Read the issue and inspect the current implementation.
- Check the working tree before making changes.
- Do not modify generated files unless the issue requires it.
- Do not access, print, or commit secrets.

## Scope
- Change only files needed for the issue.
- Do not upgrade dependencies unless explicitly requested.
- Do not alter public APIs, schemas, permissions, or deployment settings
  without a human decision.

## Verification
- Run the formatter for changed files.
- Run the focused test command.
- Run the repository's required validation command.
- Report commands and outcomes; do not claim checks that were not run.

## Stop conditions
- Stop if acceptance criteria conflict.
- Stop if a required behavior is ambiguous.
- Stop before handling production data or credentials.
- Stop before changing security, billing, permissions, migrations, or
  externally visible contracts.
- Stop if verification cannot be run or its result cannot be interpreted.

Instructions should describe observable actions. “Use good judgment” is not reproducible. “If a database migration is required, stop and request human review” is reproducible.

4. Add a preflight before implementation

Before editing, the agent should produce a preflight record. This can be a comment on the issue, a local log, or the initial merge-request description.

Issue: #123
Selected because: opened + agent-ready + small + unassigned
Intended scope: src/validator.ts and test/validator.test.ts
Acceptance criteria:
- [ ] ...
- [ ] ...
Planned checks:
- npm test -- --runInBand test/validator.test.ts
- npm run lint -- src/validator.ts
Known stop conditions:
- public contract changes
- dependency changes
- migration or permission changes

The preflight is useful even when the task later stops. It shows what the agent believed it was authorized to do and makes scope drift easier to detect.

5. Keep changes scoped

Scope is a measurable constraint. Before and after the change, inspect the working tree and the diff.

git status --short
git diff --stat
git diff -- src/validator.ts test/validator.test.ts

These commands are examples, not evidence that they were run for this article. In a real run, record the actual commands and their outputs in the merge request.

A useful scope policy is:

If the smallest correct solution crosses a declared boundary, stop and explain why. Scope expansion is a decision, not a side effect.

6. Verification should have layers

One green test is not a complete verification strategy. Use layers that match the change.

Layer 1: fast local checks

Run formatting, linting, type checking, or a focused unit test for the changed code. These checks provide quick feedback while the agent is working.

# Examples only; use commands defined by the repository
npm run format:check
npm run lint
npm test -- --runInBand path/to/changed.test.ts

Layer 2: required repository checks

Run the checks documented by the repository or configured in the CI pipeline. The agent must not substitute a convenient check for a required one without stating the difference.

A minimal GitLab configuration might look like this:

stages:
  - verify

verify:
  stage: verify
  image: node:22
  script:
    - npm ci
    - npm run format:check
    - npm run lint
    - npm test -- --runInBand
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

This is an example configuration. It is not a claim that every project should use Node.js, this image, or these commands.

Layer 3: change-specific checks

For a parser change, test malformed input. For an authorization change, test both allowed and denied paths. For a migration, verify the migration plan and rollback behavior with a human. For a UI change, include the project’s documented browser or visual checks if available.

Layer 4: human review

Automated checks can establish that selected conditions passed. They cannot decide whether the issue was the right product decision, whether an error message is appropriate, or whether a security trade-off is acceptable. Those are review questions.

7. Define stop conditions before the agent starts

Stop conditions are part of the workflow, not a failure of the agent. They prevent silent decisions in areas where repository evidence is insufficient.

The agent should stop and request human review when:

A stop report should be specific:

STOPPED: human decision required

Reason:
The requested behavior changes the public response schema.

Evidence:
The current endpoint returns fields A and B. The issue requests field C,
but does not specify compatibility requirements for existing clients.

Completed:
- Inspected the endpoint and its tests.
- Added no code.
- No verification commands were run.

Decision needed:
Should the schema change be backward-compatible, versioned, or rejected?

“I got stuck” is not enough. A useful stop report separates observed facts from interpretation and states the smallest decision needed to continue.

8. Use GitLab as the audit trail

A merge request should make the work reviewable without reconstructing the agent’s session. Include:

For example:

## Verification

Run:
- `npm run lint -- src/validator.ts` — passed
- `npm test -- --runInBand test/validator.test.ts` — passed

Not run:
- full browser suite — not available in this environment

Limitations:
- This verifies the focused validator path only.
- No production data or external service was accessed.

Do not write “all tests pass” unless all required tests actually ran and their result is known. Do not convert an unavailable check into a pass.

9. A small queue controller

The queue can be implemented with a scheduled job, a manually invoked script, or an agent orchestration service. The mechanism is less important than the state transitions.

for issue in ordered_open_issues:
    if not is_eligible(issue):
        continue

    if not claim(issue):
        continue

    context = load_issue_and_repository_instructions(issue)

    if context.has_stop_condition:
        report_stop(issue, context.reason)
        release_or_mark(issue, "needs-clarification")
        continue

    result = agent_implement(issue, context)

    if result.scope_expanded:
        report_stop(issue, "scope expansion")
        continue

    verification = run_required_checks(result)

    if verification.incomplete:
        report_stop(issue, verification.reason)
        continue

    open_merge_request(issue, result, verification)
    break

This pseudocode deliberately leaves several decisions open: how to authenticate, how to order issues, how to recover abandoned claims, and which checks are required. Those decisions belong in the repository or platform runbook rather than being silently guessed by the agent.

10. Failure cases to test

A reproducible workflow should be tested against failure, not only the happy path.

Failure Expected behavior
Issue has no acceptance criteria Do not claim it; add needs-clarification or request review.
Issue is assigned after selection Abort the claim and re-read the queue.
Required test command is missing Stop and report the missing repository instruction.
Unexpected file appears in the diff Investigate; revert only with an approved, recoverable process or stop.
Test fails due to an unrelated environment problem Report the failure and its evidence; do not call it passed.
Issue requires a migration Stop before changing the schema unless the workflow explicitly authorizes it.
Two workers claim the same issue Keep one authoritative merge request and close or reconcile the duplicate manually.

11. Limitations

This workflow reduces accidental automation; it does not prove correctness. Labels can be wrong, issue descriptions can be incomplete, tests can be insufficient, and CI can pass while the product behavior is still undesirable. A repository may also contain instructions that conflict with organizational policy. Human ownership remains necessary for high-impact decisions.

Do not treat the queue as a permission system. Use GitLab permissions, protected branches, protected environments, secret management, and least-privilege credentials for that purpose. The article does not prescribe a particular GitLab configuration, runner architecture, or agent product because those details must be verified against the actual environment.

Practical checklist

Conclusion

A GitLab issue queue becomes suitable for coding agents when it behaves like a small control system: deterministic selection, explicit authority, repository-local instructions, layered verification, narrow diffs, and visible stop conditions. The result is not autonomous software development. It is a repeatable path from an approved issue to a reviewable change, with uncertainty surfaced before it becomes an irreversible decision.

For related terminology, see the Agent Lab Journal glossary. For more workflows and implementation guides, continue to the guides index.

We publish what works for us—and implement the same solutions for your business. We design AI automation, Telegram bots, chats, and AI agents for real-world processes. Discuss your project →