Push without starting a run: [skip flow] (closes #284) 367f34b8e590

-- Pushing without a run (oxygenhub#284): `[skip flow]`, `[skip ci]` or

-- `[ci skip]` in the newest pushed change's message records a skipped run

-- instead of starting jobs. Where a maintainer allows it: `any` bookmark

-- (the default), `others` than the default bookmark, or `never`.

ALTER TABLE repositories ADD COLUMN flow_skip TEXT NOT NULL DEFAULT 'any';

-- A skipped run is recorded with status `skipped`.

ALTER TABLE flow_runs DROP CONSTRAINT flow_runs_status_check;

ALTER TABLE flow_runs ADD CONSTRAINT flow_runs_status_check

    CHECK (status IN ('queued', 'running', 'passed', 'failed', 'error', 'cancelled', 'skipped'));

-- Pushing without a run (oxygenhub#284): `[skip flow]`, `[skip ci]` or

-- `[ci skip]` in the newest pushed change's message records a skipped run

-- instead of starting jobs. Where a maintainer allows it: `any` bookmark

-- (the default), `others` than the default bookmark, or `never`.

ALTER TABLE repositories ADD COLUMN flow_skip TEXT NOT NULL DEFAULT 'any';

-- A skipped run is recorded with status `skipped`. SQLite cannot change a

-- CHECK constraint in place, so flow_runs is rebuilt as in 0033 (with

-- foreign keys off during migrations, its jobs and reports stay).

CREATE TABLE flow_runs_new (

    id            INTEGER PRIMARY KEY,

    repo_id       INTEGER NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,

    bookmark      TEXT NOT NULL,

    -- The bookmark's state hash (checks are keyed by it) and its heads, joined with '+'.

    state         TEXT NOT NULL,

    heads         TEXT NOT NULL,

    pipeline_hash TEXT NOT NULL DEFAULT '',

    status        TEXT NOT NULL CHECK (status IN ('queued', 'running', 'passed', 'failed', 'error', 'cancelled', 'skipped')),

    -- Pipeline problems, one per line, for a run in error; why, for a skipped one.

    error         TEXT NOT NULL DEFAULT '',

    actor         TEXT NOT NULL DEFAULT '',

    created_ms    INTEGER NOT NULL,

    finished_ms   INTEGER,

    number        INTEGER NOT NULL DEFAULT 0,

    trigger       TEXT NOT NULL DEFAULT 'push',

    priority      TEXT NOT NULL DEFAULT '',

    priority_note TEXT NOT NULL DEFAULT ''

);

INSERT INTO flow_runs_new (id, repo_id, bookmark, state, heads, pipeline_hash, status, error, actor, created_ms, finished_ms, number, trigger, priority, priority_note)

    SELECT id, repo_id, bookmark, state, heads, pipeline_hash, status, error, actor, created_ms, finished_ms, number, trigger, priority, priority_note FROM flow_runs;

DROP TABLE flow_runs;

ALTER TABLE flow_runs_new RENAME TO flow_runs;

CREATE INDEX flow_runs_by_repo ON flow_runs (repo_id, id DESC);

CREATE UNIQUE INDEX flow_runs_number ON flow_runs (repo_id, number);

- **Push without starting a run (#284):** `[skip flow]`, `[skip ci]` or `[ci skip]` in the newest pushed change's message starts no jobs; the run list shows a skipped run naming the change and who pushed it, and the next run still tests what it brought. Tags always run. Maintainers choose where it is allowed under Settings › Runs: any bookmark (the default), any but the default bookmark, or never.

/// A push that asked for no run (#284): recorded, finished, as skipped,

/// with `why` (which change asked, and who pushed it) as its note.

pub async fn create_skipped_run(pool: &Pool, r: NewRun<'_>, why: &str) -> sqlx::Result<i64> {

    let mut tx = super::begin_write(pool).await?;

    let now = now_ms();

    let id: i64 = sqlx::query_scalar(

        "INSERT INTO flow_runs (repo_id, number, bookmark, state, heads, pipeline_hash, status, error, actor, trigger, created_ms, finished_ms) \

         VALUES ($1, (SELECT COALESCE(MAX(number), 0) + 1 FROM flow_runs WHERE repo_id = $2), $3, $4, $5, $6, 'skipped', $7, $8, $9, $10, $11) RETURNING id",

    )

    .bind(r.repo_id)

    .bind(r.repo_id)

    .bind(r.bookmark)

    .bind(r.state)

    .bind(r.heads)

    .bind(r.pipeline_hash)

    .bind(why)

    .bind(r.actor)

    .bind(r.trigger)

    .bind(now)

    .bind(now)

    .fetch_one(&mut *tx)

    .await?;

    tx.commit().await?;

    Ok(id)

}

        "SELECT * FROM flow_runs WHERE repo_id = $1 AND bookmark = $2 AND heads != '' AND status NOT IN ('cancelled', 'skipped')

    /// Where a push may skip its run with `[skip flow]` (#284, migration

    /// 0088): `any` bookmark, `others` than the default one, or `never`.

    #[sqlx(default)]

    pub flow_skip: String,

pub async fn set_flow_skip(pool: &Pool, id: i64, skip: &str) -> sqlx::Result<()> {

    sqlx::query("UPDATE repositories SET flow_skip = $1 WHERE id = $2").bind(skip).bind(id).execute(pool).await?;

    Ok(())

}

            // `[skip flow]` in the newest change it brings (#284): recorded,

            // no jobs.

            if let Some((change, marker)) = skip_asked(app, row, bookmark, heads).await {

                skip_run(app, row, bookmark, state, heads, actor, &change, marker).await;

                return;

            }

    }

}

/// The markers that ask a push not to start a run (#284), as the forges

/// spell them; matched in any case.

pub const SKIP_MARKERS: [&str; 3] = ["[skip flow]", "[skip ci]", "[ci skip]"];

/// The marker in `message` that asks for no run, if any.

pub fn skip_marker(message: &str) -> Option<&'static str> {

    let m = message.to_lowercase();

    SKIP_MARKERS.into_iter().find(|k| m.contains(k))

}

/// Whether the repository lets a push to `bookmark` skip its run: `any`

/// bookmark (the default), `others` than the default one, or `never`.

pub fn skip_allowed(row: &db::repos::RepoRow, bookmark: &str) -> bool {

    match row.flow_skip.as_str() {

        "never" => false,

        "others" => bookmark != row.default_bookmark,

        _ => true,

    }

}

/// The newest change of `heads` (by its clock) when its message asks for

/// no run and the repository allows that here: its hash and the marker.

async fn skip_asked(app: &Shared, row: &db::repos::RepoRow, bookmark: &str, heads: &[ChangeHash]) -> Option<(ChangeHash, &'static str)> {

    if !skip_allowed(row, bookmark) {

        return None;

    }

    let repo = RepoName::new(&row.owner, &row.name)?;

    let h = heads.to_vec();

    let newest = app

        .repos

        .read(&repo, move |r, _| {

            let mut best: Option<(oxy_core::objects::Hlc, ChangeHash, String)> = None;

            for x in &h {

                let (c, _) = r.store().get_change_lazy(x)?;

                if best.as_ref().is_none_or(|(t, _, _)| c.hlc > *t) {

                    best = Some((c.hlc, *x, c.message.clone()));

                }

            }

            Ok(best)

        })

        .await

        .ok()??;

    skip_marker(&newest.2).map(|m| (newest.1, m))

}

/// Record a push's run as skipped (#284): finished, with no jobs, saying

/// which change asked and who pushed it. The next run's scope still covers

/// what this push brought, as a skipped run is never its baseline.

#[allow(clippy::too_many_arguments)]

async fn skip_run(

    app: &Shared,

    row: &db::repos::RepoRow,

    bookmark: &str,

    state: &str,

    heads: &[ChangeHash],

    actor: &str,

    change: &ChangeHash,

    marker: &str,

) {

    let mut hex: Vec<String> = heads.iter().map(|h| h.to_hex()).collect();

    hex.sort();

    let heads_s = hex.join("+");

    let why = format!("{marker} in change {}, pushed by {actor}", change.short(12));

    let base =

        db::flow::NewRun { repo_id: row.id, bookmark, state, heads: &heads_s, pipeline_hash: "", actor, trigger: "push", error: None };

    if let Err(e) = db::flow::create_skipped_run(&app.db, base, &why).await {

        tracing::warn!("flow: recording a skipped run of {}/{}: {e}", row.owner, row.name);

        .route("/{owner}/{name}/settings/flow-skip", post(repo_settings::flow_skip))

pub struct SkipForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    /// `any`, `others` or `never`.

    skip: String,

}

/// `POST /{owner}/{repo}/settings/flow-skip` (oxygenhub#284): where a push

/// may skip its run with `[skip flow]` in its message; for maintainers,

/// audited.

pub async fn flow_skip(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Form(f): Form<SkipForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/settings"), &viewer);

    let (_, row, _) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Maintain).await?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    let notice = match f.skip.as_str() {

        "any" => "A push may now skip its run on any bookmark.".to_string(),

        "others" => format!("A push may now skip its run on any bookmark but {}.", row.default_bookmark),

        "never" => "Every push now runs; skip markers are ignored.".to_string(),

        _ => return back(&row, Section::Runs, None, Some("Choose where a push may skip its run.".into())),

    };

    db::repos::set_flow_skip(&app.db, row.id, &f.skip).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    accounts::audit(&app.db, viewer.account(), "repo.flow_skip", &format!("{owner}/{name}"), &f.skip).await.ok();

    back(&row, Section::Runs, Some(notice), None)

}

#[derive(Deserialize)]

    assert!(

        runs.contains("id=\"flow-priority\"")

            && runs.contains("id=\"flow-supersede\"")

            && runs.contains("id=\"flow-skip\"")

            && !runs.contains("id=\"general\"")

    );

        ("/flow-skip", "skip=others", "runs", "skip its run on any bookmark but main"),

        ("/flow-skip", "skip=sometimes", "runs", "Choose where a push may skip its run."),

/// oxygenhub#284: a push whose newest change says `[skip ci]` records a

/// skipped run with no jobs; the next run's scope still covers what it

/// brought; and a repository can refuse skips on its default bookmark.

#[tokio::test(flavor = "multi_thread")]

async fn a_push_can_skip_its_run() {

    let h = hub().await;

    db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", true).await.unwrap();

    create(&h.app, "andy", "skip").await;

    let url = format!("{}/andy/skip", h.base);

    let work = tempfile::tempdir().unwrap();

    let c = client(&url, work.path());

    let extra = "job \"dist\" {\n    sandbox \"alpine\"\n    scope \"Cargo.toml\"\n    exec \"true\"\n}\n";

    write(work.path(), ".flow/pipeline.kdl", &pipeline(extra));

    write(work.path(), "test.sh", "echo ok\n");

    write(work.path(), "Cargo.toml", "version = \"0.1.0\"\n");

    c.commit("Start", &[]).unwrap();

    assert!(c.push("origin", false).unwrap().iter().all(|r| r.ok));

    let newest = |app: Shared, n: usize| async move {

        for _ in 0..100 {

            let runs = runs_of(&app, "andy", "skip").await;

            if runs.len() >= n {

                assert_eq!(runs.len(), n, "runs");

                let r = runs[0].clone();

                let mut jobs: Vec<String> = db::flow::jobs(&app.db, r.id).await.unwrap().into_iter().map(|j| j.name).collect();

                jobs.sort();

                if r.status != "skipped" {

                    sqlx::query("UPDATE flow_runs SET status = 'passed' WHERE id = $1").bind(r.id).execute(&app.db).await.unwrap();

                }

                return (r, jobs);

            }

            tokio::time::sleep(std::time::Duration::from_millis(50)).await;

        }

        panic!("no run {n}");

    };

    assert_eq!(newest(h.app.clone(), 1).await.1, ["build", "dist", "lint", "test"]);

    // Skipped: recorded, finished, no jobs, saying which change and who.

    write(work.path(), "Cargo.toml", "version = \"0.1.1\"\n");

    c.commit("Bump the version [Skip CI]", &[]).unwrap();

    assert!(c.push("origin", false).unwrap().iter().all(|r| r.ok));

    let (run, jobs) = newest(h.app.clone(), 2).await;

    assert_eq!(run.status, "skipped");

    assert!(jobs.is_empty(), "{jobs:?}");

    assert!(run.error.starts_with("[skip ci] in change ") && run.error.contains(", pushed by "), "{}", run.error);

    assert!(run.finished_ms.is_some());

    let (_, page) = call(&h.app, "GET", "/andy/skip/flow/2", None, None).await;

    assert!(page.contains("the push asked to skip this run"), "{page}");

    // The next run is scoped against run 1, so it still runs dist for the

    // version the skipped push brought.

    write(work.path(), "test.sh", "echo still ok\n");

    c.commit("Edit the test", &[]).unwrap();

    assert!(c.push("origin", false).unwrap().iter().all(|r| r.ok));

    assert_eq!(newest(h.app.clone(), 3).await.1, ["build", "dist", "lint", "test"], "the skipped bump still runs dist");

    // Not on the default bookmark: the marker is ignored there.

    let row = db::repos::get(&h.app.db, "andy", "skip").await.unwrap().unwrap();

    db::repos::set_flow_skip(&h.app.db, row.id, "others").await.unwrap();

    write(work.path(), "test.sh", "echo ok again\n");

    c.commit("Docs only [skip flow]", &[]).unwrap();

    assert!(c.push("origin", false).unwrap().iter().all(|r| r.ok));

    let (run, jobs) = newest(h.app.clone(), 4).await;

    assert_ne!(run.status, "skipped");

    assert_eq!(jobs, ["build", "lint", "test"]);

    let row = db::repos::get(&h.app.db, "andy", "skip").await.unwrap().unwrap();

    assert!(oxygenhub::flow::skip_allowed(&row, "feature") && !oxygenhub::flow::skip_allowed(&row, "main"));

    db::repos::set_flow_skip(&h.app.db, row.id, "never").await.unwrap();

    let row = db::repos::get(&h.app.db, "andy", "skip").await.unwrap().unwrap();

    assert!(!oxygenhub::flow::skip_allowed(&row, "feature"));

}

#[test]

fn skip_markers_are_the_forges_spellings_in_any_case() {

    use oxygenhub::flow::skip_marker;

    assert_eq!(skip_marker("Fix typo [skip flow]"), Some("[skip flow]"));

    assert_eq!(skip_marker("[CI SKIP] docs"), Some("[ci skip]"));

    assert_eq!(skip_marker("Docs\n\n[Skip CI]"), Some("[skip ci]"));

    assert_eq!(skip_marker("skip ci without brackets"), None);

}

| `/{owner}/{name}/settings/{page}` | A repository's settings (oxygenhub#278), one page per setting, with a sidebar of grouped pages beside it and the current one marked (`aria-current`); on a narrow screen the sidebar is a compact list above the page. **General**: General (`general`; `/settings` shows it), Collaborators (`collaborators`). **Code**: Landing rules (`landing`), Required checks (`checks`), Push protection (`push-protection`). **Flow**: Pipelines (`flow`: OxygenFlow on or off), Runs & priority (`runs`: priority, newest run wins, pushing without a run), Gates & agents (`gates`), Runners (`runners`), Variables (`variables`), Secrets (`secrets`), Coverage (`coverage`). **Integrations**: Webhooks (`webhooks`), AI assistants (`assistants`), Git mirror (`git-mirror`), Diffusion (`diffusion`). **Data**: Storage (`storage`, a repository kept in a bucket only), Backup (`backup`). **Danger zone**: Advanced (`advanced`: transfer, archive, delete wiki data, delete). The repository's maintainers have the pages; Collaborators, Runners, Variables, Secrets, Webhooks, AI assistants, Storage and Advanced are its admins' only, left out of the sidebar and not found for others. An archived repository's settings are its admins' only. Each form posts to its own path, as before, and redirects to the page that holds it with a notice or an error; a runner's registration token is shown once on the Runners page. A kept link to the former one-page settings, `/settings#section`, opens the page that has that section (`hub.js`). Names such as *Settings › Push protection* are these pages |

- **Pushing without a run** (oxygenhub#284). A push whose newest change (by its clock) has `[skip flow]`, `[skip ci]` or `[ci skip]` in its message, in any case, starts no jobs: the hub records a run with status `skipped`, finished at once, whose note names the marker, the change and who pushed it, so the run list shows the gap. The marker is in a signed message, so who skipped is verifiable. A skipped run is never a later run's baseline: the next push run's scope reaches back past it, so the changes it brought are still tested. A pushed tag always runs. A repository's maintainers choose under Settings › Runs where skipping is allowed: on any bookmark (the default), on any but the default bookmark, or never (`repositories.flow_skip`: `any`, `others`, `never`; audited as `repo.flow_skip`).

{% if run.status == "skipped" %}

<section class="panel"><div class="strip">No jobs ran: the push asked to skip this run ({{ run.error }}). The next run of {{ run.bookmark }} covers what it brought.</div></section>

{% else if run.status == "error" %}

    <td class="flow-dots">{% for (n, s) in row.jobs %}<span class="flow-glyph st-{{ s }}" title="{{ n }}: {{ s }}">{{ crate::web::flow::glyph(s) }}</span>{% endfor %}{% if row.r.status == "error" %}<span class="small bad">pipeline invalid</span>{% else if row.r.status == "skipped" %}<span class="small mute" title="{{ row.r.error }}">skipped by its push</span>{% endif %}</td>

<form class="card wide" id="flow-skip" method="post" action="{{ repo.url }}/settings/flow-skip">

  <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

  <h2>Pushing without a run</h2>

  <p>A push whose newest change says <code>[skip flow]</code>, <code>[skip ci]</code> or <code>[ci skip]</code> in its message starts no jobs: the run list shows it as skipped, with the change and who pushed it, and the next run still covers what it brought. A pushed tag always runs.</p>

  <select name="skip" aria-label="Where a push may skip its run">

    <option value="any"{% if row.flow_skip != "others" && row.flow_skip != "never" %} selected{% endif %}>on any bookmark</option>

    <option value="others"{% if row.flow_skip == "others" %} selected{% endif %}>on any bookmark but {{ row.default_bookmark }}</option>

    <option value="never"{% if row.flow_skip == "never" %} selected{% endif %}>never: every push runs</option>

  </select>

  <button type="submit">SAVE</button>

</form>