tenseleyflow/shithub / de4f850

+

+## Actions smoke fixture

+

+`actions/smoke-run-only.yml` is the canonical first end-to-end Actions

+workflow fixture. Copy it into `.shithub/workflows/smoke.yml` in a

+repository with a registered `ubuntu-latest` runner. It intentionally uses only

+`run:` steps because the current executor rejects reserved `uses:` aliases

+until checkout and artifact execution are implemented.

+name: smoke

+on: [push, workflow_dispatch]

+jobs:

+  hello:

+    runs-on: ubuntu-latest

+    env:

+      RUN_ID: ${{ shithub.run_id }}

+    steps:

+      - run: echo "hello from shithub actions"

+      - run: test -n "$RUN_ID"

+Exactly three aliases are reserved at parse time, no exceptions:

+| Alias                            | Parser status | Runner status                              |

+| -------------------------------- | ------------- | ------------------------------------------ |

+| `actions/checkout@v4`            | accepted      | rejected until checkout support lands      |

+| `shithub/upload-artifact@v1`     | accepted      | rejected until artifact upload lands       |

+| `shithub/download-artifact@v1`   | accepted      | rejected until artifact download lands     |

+The current Docker executor runs `run:` steps only. It fails a reserved

+`uses:` alias deliberately instead of pretending checkout/artifact

+semantics exist. This keeps the first end-to-end smoke path honest:

+`run:`-only workflows are executable now, while repository checkout and

+artifact transfer remain explicit follow-up work.

+

+This is the operator runbook for shithub Actions. Host provisioning lives in

+[runner-deploy.md](./runner-deploy.md), and runner protocol details live in

+[actions-runner-api.md](../actions-runner-api.md).

+

+## Shape

+

+```text

+git push / workflow_dispatch / schedule / pull_request

+        |

+        v

+workflow:trigger worker job

+        |

+        v

+workflow_runs + workflow_jobs + workflow_steps + check_runs

+        |

+        v

+registered runner heartbeat claims a matching queued job

+        |

+        v

+containerized run: steps -> log chunks -> step/job status -> run rollup

+```

+

+The v1 executor supports containerized `run:` steps. The parser reserves

+`actions/checkout@v4`, `shithub/upload-artifact@v1`, and

+`shithub/download-artifact@v1`, but the Docker runner rejects `uses:` steps

+until checkout metadata and artifact transfer are wired end to end. Do not use

+`actions/checkout@v4` in production smoke workflows yet.

+

+## First smoke

+

+1. Confirm migrations are applied and the web process can enqueue workers.

+2. Register one runner with a label that matches the workflow:

+

+```sh

+shithubd admin runner register \

+  --name smoke-runner-1 \

+  --labels self-hosted,linux,ubuntu-latest \

+  --capacity 1

+```

+

+3. Start `shithubd-runner` with the printed token. For production hosts, use

+   the Ansible/systemd path in [runner-deploy.md](./runner-deploy.md).

+4. Push a `run:`-only workflow:

+

+```yaml

+name: smoke

+on: [push, workflow_dispatch]

+jobs:

+  hello:

+    runs-on: ubuntu-latest

+    env:

+      RUN_ID: ${{ shithub.run_id }}

+    steps:

+      - run: echo "hello from shithub actions"

+      - run: test -n "$RUN_ID"

+```

+

+5. Expected result:

+

+- `workflow:trigger` enqueues a workflow run.

+- A runner heartbeat claims the queued job within one idle poll interval.

+- The Actions run page streams step logs while the job is running.

+- The matching check run completes with `success`.

+- `/{owner}/{repo}/actions.atom` includes the completed run.

+

+Repeat with `exit 1`; the check should complete with `failure`.

+

+

+## Runner health

+

+On the runner host:

+

+```sh

+systemctl status shithubd-runner

+journalctl -u shithubd-runner -n 100 --no-pager

+```

+

+On the app host, inspect runner registration and heartbeat state:

+

+```sh

+shithubd admin actions runner list

+```

+

+Important metrics:

+

+- `shithub_actions_runner_heartbeats_total{result="claimed|no_job"}`

+- `shithub_actions_runner_jwt_total{result="issued|rejected|replay"}`

+- `shithub_actions_jobs_cancelled_total{reason="user|concurrency|timeout"}`

+- `shithub_actions_log_scrub_replacements_total{location="server"}`

+- `shithub_actions_step_timeouts_total`

+

+## Emergency cancel

+

+Start with a dry run:

+

+```sh

+shithubd admin actions cancel-all --dry-run --limit 100

+```

+

+Scope to one repository when possible:

+

+```sh

+shithubd admin actions cancel-all --dry-run --repo-id 42

+```

+

+Then confirm:

+

+```sh

+shithubd admin actions cancel-all --confirm --repo-id 42

+```

+

+Queued jobs are marked cancelled immediately. Running jobs receive

+`cancel_requested=true`; the runner sees that through `/cancel-check`, kills the

+active container, and reports terminal `cancelled`.

+

+## Common failures

+

+- **Run never appears:** confirm the workflow file is under

+  `.shithub/workflows/`, parse it with `shithubd admin actions parse <file>`,

+  and verify the trigger event matches `on:`.

+- **Run stays queued:** confirm a runner is registered with matching labels and

+  capacity, then inspect runner journal output and heartbeat metrics.

+- **Step logs buffer:** verify the Caddy route above and confirm the SSE route

+  is still mounted outside compression and short timeouts.

+- **`uses:` step fails:** expected for now. Replace with a `run:` step until

+  checkout/artifact support lands.

+- **Secrets appear masked inconsistently:** check

+  `shithub_actions_log_scrub_replacements_total{location="server"}` and confirm

+  the job was claimed after the secret was created or rotated. Mask snapshots

+  are captured at claim time.

+- [Actions](./user/actions.md)

+# Actions

+

+shithub Actions runs CI workflows from `.shithub/workflows/*.yml`.

+The workflow format intentionally follows the parts of GitHub Actions that are

+useful for ordinary repository CI, while keeping the runner surface small enough

+to secure.

+

+## Minimal workflow

+

+```yaml

+name: smoke

+on: [push, workflow_dispatch]

+jobs:

+  hello:

+    runs-on: ubuntu-latest

+    env:

+      RUN_ID: ${{ shithub.run_id }}

+    steps:

+      - run: echo "hello from shithub actions"

+      - run: test -n "$RUN_ID"

+```

+

+Commit that file as `.shithub/workflows/smoke.yml` and push to the repository.

+The run appears under the repository's Actions tab and its job also appears as

+a check run on matching pull requests.

+

+## What works today

+

+- `push`, `pull_request`, `schedule`, and `workflow_dispatch` triggers

+- `run:` steps executed in the operator-configured runner image

+- `runs-on:` label matching against registered runners

+- workflow, job, and step `env:`

+- `${{ secrets.NAME }}`, `${{ vars.NAME }}`, `${{ env.NAME }}`, and

+  `${{ shithub.* }}` expressions

+- `needs:`, `if:`, `timeout-minutes:`, and concurrency groups

+- live step logs, cancel, re-run, check-run sync, and the Actions Atom feed

+

+`runs-on: ubuntu-latest` is a runner label, not a promise that shithub downloads

+a hosted Ubuntu image for you. The site operator decides which image a matching

+runner uses. On shithub.sh, use the labels published by the instance operator.

+

+## Current limit

+

+Use `run:` steps for now. The parser accepts these reserved aliases:

+

+- `actions/checkout@v4`

+- `shithub/upload-artifact@v1`

+- `shithub/download-artifact@v1`

+

+The runner does not execute them yet. A workflow containing those `uses:` steps

+will fail until checkout and artifact execution land. If you need repository

+files in a smoke workflow today, keep the command self-contained or fetch what

+you need explicitly inside a `run:` step.

+

+## Expressions

+

+Use the shithub namespace:

+

+```yaml

+env:

+  REF: ${{ shithub.ref }}

+  SHA: ${{ shithub.sha }}

+  RUN_ID: ${{ shithub.run_id }}

+```

+

+The `github.*` namespace is accepted as a compatibility alias for the fields

+shithub exposes, but new workflows should use `shithub.*`.

+

+Event payload values such as `${{ shithub.event.pull_request.title }}` are

+treated as untrusted. The runner passes them through temporary environment

+bindings instead of splicing them directly into shell command text.

+

+## Secrets and variables

+

+Repository and organization settings expose Actions secrets and variables.

+Secrets are encrypted at rest and are redacted from logs. Variables are

+plaintext configuration and are suitable for non-secret values such as tool

+versions or feature flags.

+

+Repo-scoped values shadow organization-scoped values with the same name.

+

+## Migrating from GitHub Actions

+

+Most simple CI files need three edits:

+

+1. Move the workflow file from `.github/workflows/` to `.shithub/workflows/`.

+2. Replace `uses:` actions with equivalent `run:` commands.

+3. Confirm `runs-on:` matches a label registered by your shithub operator.

+

+Marketplace actions, Docker actions, composite actions, hosted runner images,

+matrix expansion, service containers, and built-in checkout are not part of the

+current v1 runner.