Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/contributing/gitlab-role-credentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@ GitLab permissions than the implementation uses.
| Job | Role |
| --- | --- |
| GitLab poller/controller (`fullsend poll`, `fullsend-poll.yml`) | Poller |
| GitLab webhook dispatcher (`fullsend poll --input-driver gitlab-webhook`, `fullsend-dispatcher.yml`) | Poller |
| Agents / harness roles `review`, `triage`, `prioritize`, `retro`, `scribe` | Analyst |
| Agents / harness roles `code`, `fix`, `coder` | Coder |
| Custom agent whose name or harness `role:` is listed on a registered custom role | That custom role |
Expand Down Expand Up @@ -258,9 +259,10 @@ unlisted), exports `GITLAB_TOKEN` from that secret, and sets
`approve_merge_request`. Selection also publishes non-secret diagnostic
env vars `FULLSEND_GITLAB_ROLE`, `FULLSEND_GITLAB_ROLE_SECRET`, and
`FULLSEND_GITLAB_ROLE_SOURCE`.
GitLab CI templates (`fullsend-poll.yml`, `fullsend-agent.yml`) source
`run-poll-job.sh` and `run-agent-job.sh`, which resolve credentials via
`select-gitlab-role-token.sh`. Both job scripts first source
GitLab CI templates (`fullsend-poll.yml`, `fullsend-dispatcher.yml`,
`fullsend-agent.yml`) source `run-poll-job.sh`, `run-dispatcher-job.sh`, and
`run-agent-job.sh`, which resolve credentials via
`select-gitlab-role-token.sh`. All three job scripts first source
`pin-ci-job-identity.sh`, which takes project, pipeline, and ref from
the `CI_JOB_TOKEN` job record (`GET /api/v4/job`) rather than from the
overridable `CI_PROJECT_ID` / `CI_PIPELINE_ID` / `CI_COMMIT_REF_PROTECTED`
Expand Down
18 changes: 10 additions & 8 deletions docs/guides/getting-started/configuring-gitlab.md
Original file line number Diff line number Diff line change
Expand Up @@ -885,25 +885,27 @@ external scheduler instead — see [Off-system polling](#off-system-polling)

### `workflow:` block and `auto_cancel`

Install merges an include, `poll` / `agent` stages, and workflow rules into
the existing `.gitlab-ci.yml`. Installs from before the removal of the empty
`dispatch` stage may still contain that legacy stage; converge and uninstall
clean it up. Install does not overwrite unrelated jobs.
Install merges an include, `dispatch` / `poll` / `agent` stages, and workflow
rules into the existing `.gitlab-ci.yml`. The `dispatch` stage hosts the
webhook dispatcher job (`fullsend-dispatcher.yml`), which runs only in
`trigger` pipelines started by a GitLab pipeline trigger on the protected
default branch; such a pipeline runs the dispatcher alone, never an agent
job. Install does not overwrite unrelated jobs.

When an existing, non-empty file already has a `workflow:` block, fullsend sets
`workflow.auto_cancel.on_new_commit: none` if that key is missing, and does not
overwrite an existing value. It also adds a `CI_DEBUG_TRACE` deny-before-admit
rule (`when: never`) followed by the protected-ref `schedule`/`api` rules if
the block has no `rules:` key. Because `workflow.rules` is an
rule (`when: never`) followed by the protected-ref `schedule`/`api` rules and
the protected-default-branch `trigger` rule if the block has no `rules:` key. Because `workflow.rules` is an
allowlist, ordinary push pipelines stop running in that case unless the block
already has a matching rule; add a catch-all/push rule (or an explicit
`when: always` rule) before installing, or remove the name-only `workflow:`
block so fullsend can leave it absent. When an existing, non-empty file has no
`workflow:` block, fullsend leaves it absent so push-triggered pipelines keep
running. For a missing or empty `.gitlab-ci.yml`, fullsend instead writes a
fullsend-owned `workflow:` block with a name, `auto_cancel.on_new_commit:
none`, the `CI_DEBUG_TRACE` deny rule, and protected-ref `schedule`/`api`
rules. Later ordinary push jobs added to that file likewise need additional
none`, the `CI_DEBUG_TRACE` deny rule, protected-ref `schedule`/`api`
rules, and the protected-default-branch `trigger` rule. Later ordinary push jobs added to that file likewise need additional
`workflow.rules` (or an explicit `when: always` rule), or GitLab will skip
them.

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/getting-started/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ To remove fullsend from a single repository:

**GitLab repos:**

1. Run `fullsend repos uninstall "$PROJECT_PATH"` (the full `group/subgroup/project` path) to open a PR that removes fullsend entries from `.gitlab-ci.yml` and deletes `.gitlab/ci/fullsend-pipeline.yml`, `.gitlab/ci/fullsend-agent.yml`, `.gitlab/ci/fullsend-poll.yml`, leftover `.gitlab/ci/fullsend-dispatch.yml` from installs predating #7707, `.gitlab/ci/scripts/trust-ci-server-ca.sh`, `.gitlab/ci/scripts/pin-ci-job-identity.sh`, `.gitlab/ci/scripts/select-gitlab-role-token.sh`, `.gitlab/ci/scripts/install-fullsend-cli.sh`, `.gitlab/ci/scripts/run-poll-job.sh`, `.gitlab/ci/scripts/run-agent-job.sh`, `.gitlab/ci/scripts/checkout-mr-source.sh`, and `.fullsend/config.yaml` (pass `--direct` to push those file changes to the default branch). Variables, secrets, and the `fullsend-poll-state-slash` / `fullsend-poll-state-events` branches are deleted immediately via the API. If you prefer manual removal: delete `.gitlab/ci/fullsend-*.yml`, `.gitlab/ci/scripts/*.sh`, and `.fullsend/config.yaml`, then edit `.gitlab-ci.yml` to remove the fullsend pipeline include entry, the fullsend stages (`poll`, `agent`, and `dispatch` on installs from before the empty dispatch stage was removed), the fullsend workflow rules (the `CI_DEBUG_TRACE` deny-before-admit rule, `schedule`, `api`, and `merge_request_event` on installs from before native MR dispatch was removed), and the `auto_cancel` block if fullsend added it. Only delete `.gitlab-ci.yml` entirely if it contains no non-fullsend configuration. Also delete the two poll-state branches if they are still present.
1. Run `fullsend repos uninstall "$PROJECT_PATH"` (the full `group/subgroup/project` path) to open a PR that removes fullsend entries from `.gitlab-ci.yml` and deletes `.gitlab/ci/fullsend-pipeline.yml`, `.gitlab/ci/fullsend-agent.yml`, `.gitlab/ci/fullsend-poll.yml`, `.gitlab/ci/fullsend-dispatcher.yml`, leftover `.gitlab/ci/fullsend-dispatch.yml` from installs predating #7707, `.gitlab/ci/scripts/trust-ci-server-ca.sh`, `.gitlab/ci/scripts/pin-ci-job-identity.sh`, `.gitlab/ci/scripts/select-gitlab-role-token.sh`, `.gitlab/ci/scripts/install-fullsend-cli.sh`, `.gitlab/ci/scripts/run-poll-job.sh`, `.gitlab/ci/scripts/run-dispatcher-job.sh`, `.gitlab/ci/scripts/run-agent-job.sh`, `.gitlab/ci/scripts/checkout-mr-source.sh`, and `.fullsend/config.yaml` (pass `--direct` to push those file changes to the default branch). Variables, secrets, and the `fullsend-poll-state-slash` / `fullsend-poll-state-events` branches are deleted immediately via the API. If you prefer manual removal: delete `.gitlab/ci/fullsend-*.yml`, `.gitlab/ci/scripts/*.sh`, and `.fullsend/config.yaml`, then edit `.gitlab-ci.yml` to remove the fullsend pipeline include entry, the fullsend stages (`dispatch`, `poll`, `agent`), the fullsend workflow rules (the `CI_DEBUG_TRACE` deny-before-admit rule, `schedule`, `api`, `trigger`, and `merge_request_event` on installs from before native MR dispatch was removed), and the `auto_cancel` block if fullsend added it. Only delete `.gitlab-ci.yml` entirely if it contains no non-fullsend configuration. Also delete the two poll-state branches if they are still present.

> **Note:** During install, fullsend sets `workflow.auto_cancel.on_new_commit: none` when an existing, non-empty `.gitlab-ci.yml` already has a `workflow:` block and that key is missing; it does not overwrite an existing value. If that existing block has no `rules:` key, fullsend also adds a `CI_DEBUG_TRACE` deny-before-admit rule (`when: never`) followed by the protected-ref `schedule`/`api` rules, which can stop ordinary push pipelines unless the block already has a matching rule; add a catch-all/push rule (or an explicit `when: always` rule) before installing, or remove the name-only block so fullsend can leave `workflow:` absent. If an existing, non-empty file has no `workflow:` block, fullsend leaves it absent so push-triggered pipelines are not disrupted. For a missing or empty `.gitlab-ci.yml`, fullsend writes a fullsend-owned `workflow:` block with the `CI_DEBUG_TRACE` deny rule and protected-ref `schedule`/`api` rules; later push jobs added to that file likewise need additional `workflow.rules` or an explicit `when: always` rule, or GitLab will skip them. Repos with `on_new_commit: interruptible` (or other non-`none` values) may experience agent pipeline cancellations because fullsend requires `on_new_commit: none` for reliable agent runs. If you see unexpected pipeline cancellations, set `on_new_commit: none` in your `.gitlab-ci.yml` workflow block.

Expand Down
199 changes: 198 additions & 1 deletion internal/repos/converge_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2220,7 +2220,7 @@ func TestConverge_GitLabOnlyReleaseDefaultRefWithoutGitHubClient(t *testing.T) {
func populateGitLabInstalled(fc *forge.FakeClient, owner, repo string) {
full := owner + "/" + repo
fc.FileContents[full+"/"+fullsendPipelineInclude] = []byte(" ref: v2.5.0\n")
for _, path := range gitlabAuxiliaryScriptPaths() {
for _, path := range append(gitlabAuxiliaryScriptPaths(), gitlabDispatcherPaths()...) {
content, _ := scaffold.GitLabPerRepoFile(path)
fc.FileContents[full+"/"+path] = content
}
Expand Down Expand Up @@ -2302,6 +2302,90 @@ func TestConverge_GitLab_RepairsMissingTrustScript(t *testing.T) {
t.Fatalf("convergence did not repair %s; files: %+v", gitlabTrustScriptPath, sc.files)
}

// convergeGitLabFilesCommitted runs Converge and returns the committed paths.
func convergeGitLabFilesCommitted(t *testing.T, fc *forge.FakeClient) map[string]bool {
t.Helper()
sc := &spyScaffoldCommit{}
result, err := Converge(context.Background(), gitlabConvergeCfg("acme/api"), newTestClientFactory(fc), sc.fn(), noopProgress)
if err != nil {
t.Fatalf("Converge() error: %v", err)
}
if len(result.Failed()) != 0 {
t.Fatalf("unexpected failure: %v", result.Failed()[0].Error)
}
sc.mu.Lock()
defer sc.mu.Unlock()
committed := make(map[string]bool)
for _, f := range sc.files {
if !f.Delete {
committed[f.Path] = true
}
}
return committed
}

// TestConverge_GitLab_RepairsTemplateOnlyDispatcherDeletion verifies that
// deleting only the dispatcher template (script intact) from a fully
// converged install is detected and the YAML is redelivered; otherwise the
// wrapper's local include would point at a missing file.
func TestConverge_GitLab_RepairsTemplateOnlyDispatcherDeletion(t *testing.T) {
fc := newFakeClientForBatch("acme/api")
populateGitLabInstalled(fc, "acme", "api")
populateGitLabScaffoldContent(t, fc, "acme", "api", "v2.5.0")
delete(fc.FileContents, "acme/api/"+fullsendDispatcherTemplatePath)

committed := convergeGitLabFilesCommitted(t, fc)
if !committed[fullsendDispatcherTemplatePath] {
t.Fatalf("convergence did not redeliver %s; committed: %v", fullsendDispatcherTemplatePath, committed)
}
}

// TestConverge_GitLab_UnchangedRefRolloutDeliversDispatcherFiles verifies an
// unchanged-ref rollout from a pre-dispatcher wrapper delivers both the
// dispatcher template and script together with the rewritten wrapper.
func TestConverge_GitLab_UnchangedRefRolloutDeliversDispatcherFiles(t *testing.T) {
fc := newFakeClientForBatch("acme/api")
populateGitLabInstalled(fc, "acme", "api")
populateGitLabScaffoldContent(t, fc, "acme", "api", "v2.5.0")
// Roll the install back to a pre-dispatcher state at the same ref.
for _, path := range gitlabDispatcherPaths() {
delete(fc.FileContents, "acme/api/"+path)
}
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte("# fullsend-ref: v2.5.0\n")

committed := convergeGitLabFilesCommitted(t, fc)
for _, path := range append([]string{fullsendPipelineInclude}, gitlabDispatcherPaths()...) {
if !committed[path] {
t.Errorf("unchanged-ref rollout did not deliver %s; committed: %v", path, committed)
}
}
}

func TestProbeComponents_GitLab_DispatcherFilesFollowWrapper(t *testing.T) {
probe := func(wrapper string) map[string]bool {
fc := forge.NewFakeClient()
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte(wrapper)
components, err := ProbeComponents(context.Background(), fc, "acme", "api", ForgeGitLab, GitLabForgeConfig(), nil)
if err != nil {
t.Fatalf("ProbeComponents() error: %v", err)
}
probed := make(map[string]bool)
for _, c := range components {
probed[c.Name] = true
}
return probed
}

for _, path := range gitlabDispatcherPaths() {
if probe("# pre-dispatcher wrapper\n")["scaffold:"+path] {
t.Errorf("pre-dispatcher wrapper must not require %s", path)
}
if !probe("include: " + fullsendDispatcherTemplatePath + "\n")["scaffold:"+path] {
t.Errorf("wrapper referencing the dispatcher must require %s", path)
}
}
}

func TestConverge_GitLab_RefUpgradeAndMissingHelperDedupes(t *testing.T) {
fc := newFakeClientForBatch("acme/api")
populateGitLabInstalled(fc, "acme", "api")
Expand Down Expand Up @@ -4233,6 +4317,10 @@ workflow:
}

func TestConverge_GitLab_MigratesObsoleteDispatchStage(t *testing.T) {
// Exercises the generic obsolete-stage migration against the
// historical contract; #7771 made "dispatch" current again (see
// TestConverge_GitLab_PreservesReinstatedDispatchStage).
useHistoricalObsoleteDispatchStage(t)
fc := newFakeClientForBatch("acme/api")
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte(" ref: v2.5.0\n")
fc.VariableValues["acme/api/"+forge.VarLastPollAtFast] = "2026-01-01T00:00:00Z"
Expand Down Expand Up @@ -4325,7 +4413,112 @@ stages:
}
}

// TestConverge_GitLab_PreservesReinstatedDispatchStage verifies that, since
// #7771 reinstated "dispatch" for the webhook dispatcher job, converge never
// strips it from an enrolled root and backfills it — together with the
// source=trigger workflow rule — into roots enrolled while it was obsolete.
// Without both, GitLab would reject or skip every webhook-triggered
// dispatcher pipeline.
func TestConverge_GitLab_PreservesReinstatedDispatchStage(t *testing.T) {
fc := newFakeClientForBatch("acme/api")
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte(" ref: v2.5.0\n")
fc.Secrets["acme/api/"+forge.SecretGCPProjectID] = true
fc.Secrets["acme/api/"+forge.SecretGCPWIFProvider] = true
fc.Secrets["acme/api/"+forge.SecretForgeToken] = true
fc.PipelineSchedules["acme/api"] = []forge.PipelineSchedule{
{ID: 1, Description: "fullsend slash poll", Active: true},
{ID: 2, Description: "fullsend event poll", Active: true},
}
// Enrolled between #7337 and #7771: no dispatch stage and no trigger
// workflow rule.
fc.FileContents["acme/api/.gitlab-ci.yml"] = []byte(`---
include:
- local: '.gitlab/ci/fullsend-pipeline.yml'

stages:
- build
- poll
- agent

workflow:
rules:
- if: $CI_DEBUG_TRACE =~ /^(1|t|true)$/i
when: never
- if: $CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_REF_PROTECTED == "true"
- if: $CI_PIPELINE_SOURCE == "api" && $CI_COMMIT_REF_PROTECTED == "true" && $STAGE
`)

m := &Manifest{
Version: 1,
GitLab: &PlatformConfig{
URL: "https://gitlab.example.com",
FullsendRef: "v2.5.0",
Repos: []RepoEntry{{Name: "acme/api"}},
},
}
cfg := ConvergeConfig{
Manifest: m,
MaxConcurrency: 4,
Roles: []string{"triage"},
Direct: true,
InferenceProject: "test-inference",
InferenceProjectNumber: "123456789",
InferenceRegion: "us-central1",
}

sc := &spyScaffoldCommit{}
result, err := Converge(context.Background(), cfg, newTestClientFactory(fc), sc.fn(), noopProgress)
if err != nil {
t.Fatalf("Converge() error: %v", err)
}
if len(result.Failed()) != 0 {
t.Fatalf("expected 0 failed, got %d: %+v", len(result.Failed()), result.Results[0].Error)
}
for _, a := range result.Results[0].Actions {
if a.Component == "gitlab-ci-stages" {
t.Errorf("expected no obsolete-stage action, got %+v", a)
}
}

sc.mu.Lock()
defer sc.mu.Unlock()
var updated []byte
var committedDispatcherScript, committedDispatcherTemplate bool
for _, f := range sc.files {
switch f.Path {
case ".gitlab-ci.yml":
updated = f.Content
case gitlabDispatcherJobScriptPath:
committedDispatcherScript = true
case fullsendDispatcherTemplatePath:
committedDispatcherTemplate = true
}
}
if !committedDispatcherScript {
t.Errorf("expected converge to repair the missing dispatcher job script")
}
if !committedDispatcherTemplate {
t.Errorf("expected converge to repair the missing dispatcher job template")
}
if updated == nil {
t.Fatalf("expected .gitlab-ci.yml to be committed, got files: %+v", sc.files)
}
s := string(updated)
for _, stage := range []string{"- build", "- dispatch", "- poll", "- agent"} {
if !strings.Contains(s, stage) {
t.Errorf("expected stage %q in converged root, got:\n%s", stage, s)
}
}
if !strings.Contains(s, triggerDispatcherRuleIf) {
t.Errorf("expected trigger dispatcher workflow rule to be backfilled, got:\n%s", s)
}
if strings.Index(s, debugTraceDenyRuleIf) > strings.Index(s, triggerDispatcherRuleIf) {
t.Errorf("expected debug-trace deny rule before the trigger admit rule, got:\n%s", s)
}
}

func TestConverge_GitLab_ReplacementWrapperPermitsMigration(t *testing.T) {
useHistoricalObsoleteDispatchStage(t)
// Same root .gitlab-ci.yml shape as
// TestConverge_GitLab_MigratesObsoleteDispatchStage, but this repo's
// on-repo pipeline wrapper (.gitlab/ci/fullsend-pipeline.yml) predates
Expand Down Expand Up @@ -4419,6 +4612,7 @@ stages:
}

func TestConverge_GitLab_MigratesObsoleteRuleAndStage(t *testing.T) {
useHistoricalObsoleteDispatchStage(t)
fc := newFakeClientForBatch("acme/api")
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte(" ref: v2.5.0\n")
fc.VariableValues["acme/api/"+forge.VarLastPollAtFast] = "2026-01-01T00:00:00Z"
Expand Down Expand Up @@ -4515,6 +4709,7 @@ workflow:
}

func TestConverge_GitLab_MigratesObsoleteDispatchStage_DryRun(t *testing.T) {
useHistoricalObsoleteDispatchStage(t)
fc := newFakeClientForBatch("acme/api")
fc.FileContents["acme/api/"+fullsendPipelineInclude] = []byte(" ref: v2.5.0\n")
fc.VariableValues["acme/api/"+forge.VarLastPollAtFast] = "2026-01-01T00:00:00Z"
Expand Down Expand Up @@ -5662,11 +5857,13 @@ func gitlabRequiredScaffoldPaths() []string {
fullsendPipelineInclude,
".gitlab/ci/fullsend-agent.yml",
".gitlab/ci/fullsend-poll.yml",
".gitlab/ci/fullsend-dispatcher.yml",
".gitlab/ci/scripts/trust-ci-server-ca.sh",
".gitlab/ci/scripts/pin-ci-job-identity.sh",
".gitlab/ci/scripts/select-gitlab-role-token.sh",
".gitlab/ci/scripts/install-fullsend-cli.sh",
".gitlab/ci/scripts/run-poll-job.sh",
".gitlab/ci/scripts/run-dispatcher-job.sh",
".gitlab/ci/scripts/run-agent-job.sh",
".gitlab/ci/scripts/checkout-mr-source.sh",
".fullsend/config.yaml",
Expand Down
11 changes: 11 additions & 0 deletions internal/repos/drift.go
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,17 @@ func CheckFileContentDrift(ctx context.Context, client forge.Client,
if installed == nil {
// File not found — presence drift is handled by
// ProbeComponents; content comparison not applicable.
// Exception: the GitLab webhook dispatcher files are probed
// only when the installed wrapper already references them, so
// a rollout that is about to rewrite the wrapper must deliver
// them here when the selected version's scaffold includes them.
if forgeName == ForgeGitLab && slices.Contains(gitlabDispatcherPaths(), ef.Path) {
drifted = append(drifted, ContentDriftFile{
Path: ef.Path,
InstalledPath: ef.Path,
Expected: ef.Content,
})
}
continue
}

Expand Down
Loading
Loading