po4yka/RIPDPI / .agents/skills/ci-workflow-authoring
ci-workflow-authoring
VerifiedAdd or modify a GitHub Actions job. Use when editing a file under .github/workflows/. Not for running a workflow locally (local-ci-act) or release signing (release-signing).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
SKILL.md
View on GitHub---
name: ci-workflow-authoring
description: Add or modify a GitHub Actions job. Use when editing a file under .github/workflows/. Not for running a workflow locally (local-ci-act) or release signing (release-signing).
---
# CI Workflow Authoring
Workflow count, jobs, dispatch inputs, action versions, and concurrency rules
are source-controlled in `.github/workflows/`. Inspect the current manifests
and copy the nearest existing job; do not maintain a second hand-written
inventory here.
## CI architecture (`ci.yml`)
Derive the current job graph, triggers, dispatch inputs, and `concurrency:`
policy directly from `.github/workflows/ci.yml`; these change too often for a
second inventory here.
## Environment Setup Pattern
Most Android/native jobs reuse `.github/actions/setup-android-rust`. Copy that
composite action or the nearest current job, including every exact action SHA;
never substitute a floating tag from an example.
## Caching Strategy
| Cache | Implementation | Notes |
|-------|---------------|-------|
| Gradle | Exact pinned `gradle/actions/setup-gradle` SHA from the nearest job | Preferred over hand-rolled cache blocks |
| Rust workspace | Exact pinned `Swatinem/rust-cache` SHA from the nearest job | Caches `native/rust -> target` |
| Rust compiler cache | Exact pinned sccache action SHA from the nearest job | Used on native-heavy jobs |
| Benchmark baselines | `actions/cache/restore` / `save` | Used by criterion baselines on PRs and main |
| Tool installs | `taiki-e/install-action@v2` | Used for `cargo-nextest`, `cargo-llvm-cov`, `cargo-bloat` |
## Manual Dispatch Inputs
Derive the current inputs from the `workflow_dispatch.inputs` mapping in
`ci.yml`; it changes as optional lanes evolve. Typical inputs include:
```yaml
workflow_dispatch:
inputs:
soak_profile: smoke|full
run_native_soak: true|false
```
If you add a new manual-only lane, wire its input into both the job `if:` condition and the step logic that consumes it.
## Adding or Modifying a CI Job
Checklist:
1. Decide which workflow the job belongs in -- inspect `.github/workflows/` for the current file list and pick the nearest match; the repo has grown well past a small fixed set and this skill does not maintain a second inventory of it.
2. Copy environment setup from the nearest existing job instead of inventing a new setup pattern.
3. Read the NDK version from `gradle.properties`; never hardcode it in YAML.
4. Add `timeout-minutes` unless the job is trivially short.
5. Use `if: always()` on artifact upload steps.
6. Keep artifact names stable when downstream debugging depends on them.
7. If the job is nightly-only, gate it explicitly on `schedule` or `workflow_dispatch`.
8. If the job runs `:app` or `:baselineprofile` instrumented tests, use the Gradle Managed Device pattern: a `<device>...AndroidTest` task plus the shared device registry in `build-logic/convention/src/main/kotlin/RipDpiManagedDevices.kt` (see the `android-instrumented-tests` and `android-macrobenchmark` jobs). Specialized emulator lanes (journeys, relay-smoke, network-e2e) still use the `scripts/ci/start-android-emulator.sh` harness.
### Job template
```yaml
my-new-job:
needs: [build]
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@<copy-exact-pinned-sha-from-nearest-job>
- uses: ./.github/actions/setup-android-rust
- name: Run tests
run: ./gradlew :module:testDebugUnitTest
- uses: actions/upload-artifact@<copy-exact-pinned-sha-from-nearest-job>
if: always()
with:
name: my-results
path: module/build/reports/
retention-days: 7
```
## CodeQL Workflow (`codeql.yml`)
- The matrix analyzes `actions` and `rust` with `build-mode: none` and `java-kotlin` with `build-mode: manual`.
- The `java-kotlin` lane compiles every Kotlin module with an in-process Kotlin compiler and no build cache, so the CodeQL tracer sees each compilation. Do not replace it with autobuild.
- Before a Kotlin bump, make sure that the pinned CodeQL bundle supports the new compiler version.
## Release Workflows (`release-candidate.yml`, `release.yml`)
These are two separate workflows with different triggers -- do not conflate them:
- `release-candidate.yml` is `workflow_dispatch`-triggered. It decodes the base64 keystore secret and runs the flavor-qualified Play/Fdroid/Github release tasks to produce a signed candidate artifact.
- `release.yml` is triggered only by `v*` tag pushes (no manual dispatch). It verifies the tag against an already-successful `release-candidate.yml` run and promotes that exact, already-signed candidate; it never touches the keystore secret and never runs an assemble task itself.
This skill owns CI job authoring, not the release contract. For signing, R8 keep-rule, and versioning details, read the `release-signing` skill; for the gated multi-phase prepare-integrate-produce-publish procedure and its authorization boundaries, read the `ripdpi-release` skill.
## Mutation Testing Workflow (`mutation-testing.yml`)
- Runs `cargo-mutants` against the Rust workspace.
- Exposes manual filters such as package selection and diff-only mode.
- Produces `target/mutants-output/` artifacts.
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Hardcoding the NDK version | Read `ripdpi.nativeNdkVersion` from `gradle.properties` |
| Using outdated action versions from old workflow snippets | Copy the exact pinned SHA and version comment from the nearest current workflow job |
| Forgetting schedule/manual gating on soak or load jobs | Mirror the existing `schedule || workflow_dispatch` pattern |
| Uploading artifacts only on success | Use `if: always()` so failure artifacts are preserved |
| Letting the Gradle build cache or Kotlin daemon serve the CodeQL compile | Keep `--no-build-cache` and `kotlin.compiler.execution.strategy=in-process`, or CodeQL extracts no Kotlin |
| Hand-rolling emulator setup for instrumented tests | Use the Gradle Managed Device pattern (`RipDpiManagedDevices.kt` + a `<device>...AndroidTest` task); reserve `scripts/ci/start-android-emulator.sh` for the journeys/relay/network-e2e lanes |
## See Also
- `local-ci-act` skill -- local workflow execution with `act`.
- `release-signing` skill -- release signing and R8 details.
- `dependency-update` skill -- version changes that affect workflow setup.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |