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

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:
- Select exactly one eligible issue.
- Confirm that the issue is actionable and within the agent’s authority.
- Read repository instructions before editing.
- Make the smallest change that satisfies the acceptance criteria.
- Run the checks required by the repository.
- Report evidence, limitations, and remaining uncertainty.
- 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.
agent-ready: the issue may be selected by the agent.human-only: a person must make the change or decision.needs-clarification: acceptance criteria are incomplete.blocked: a dependency or external decision prevents work.security-review: the issue needs specialist review before implementation.agent-in-progress: a worker has claimed the issue.agent-verification-failed: the attempted change did not pass required checks.
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:
- Read the issue and record its current state, labels, assignee, and last update.
- Re-read immediately before claiming it.
- Add
agent-in-progressand assign the issue to the designated bot or service account. - Write a short comment containing the claim time, intended scope, and worker identifier.
- 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:
- What behavior is wrong or missing?
- What behavior should replace it?
- What files or component boundaries are in scope?
- How can the result be verified?
- What must not change?
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:
- Only files named in the issue or discovered as necessary may change.
- Unrelated formatting changes are not allowed.
- Dependency lockfiles may change only when dependency changes are intentional.
- Generated artifacts must be regenerated only by the documented command.
- Unexpected files require investigation and usually a stop.
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:
- Acceptance criteria conflict or leave the expected behavior ambiguous.
- The change affects authentication, authorization, secrets, privacy, or sensitive data.
- The change alters a public API, database schema, migration, billing rule, or data-retention policy.
- A dependency must be added, upgraded, removed, or replaced.
- The issue requires production access or an irreversible operation.
- Tests fail for a reason the agent cannot explain from repository evidence.
- Required checks cannot run because of missing tools, network access, credentials, or environment assumptions.
- The diff exceeds the issue’s declared scope.
- Another change has modified the same files or issue while work is in progress.
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:
- the linked issue;
- the selected acceptance criteria;
- a summary of changed files and why they changed;
- commands actually run;
- the observed result of each command;
- checks that were not run and why;
- known limitations;
- any human decision requested.
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
- Is the issue opened, labeled
agent-ready, unassigned, and current? - Does it have acceptance criteria, scope, verification steps, and explicit exclusions?
- Did the agent read the applicable repository instruction files?
- Was the issue claimed and rechecked before editing?
- Did the diff remain within scope?
- Were the required checks actually run?
- Are command results and unavailable checks recorded accurately?
- Did the agent stop before security, schema, contract, production, or other human-only decisions?
- Can a reviewer understand what changed without reading the agent’s private session?
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.