skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

authoring-ci-workflows

Guides authoring of GitHub Actions workflows following PostHog CI conventions and lint rules.

713|118|Updated Aug 11, 2020
Search Tags:#linting#ci#Caching#Workflows#GitHub actions#Concurrency#devOps
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill authoring-ci-workflows
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: authoring-ci-workflows
Source: https://github.com/PostHog/posthog-foss/tree/main/.agents/skills/authoring-ci-workflows
Command: npx skills add https://github.com/PostHog/posthog-foss --skill authoring-ci-workflows

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing or editing GitHub Actions workflows in a large public monorepo involves many non-obvious constraints: GitHub's 500-runs-per-10s dispatch cap, concurrency grouping, fork-safe secrets, checkout performance on a 4.6 GiB repo, and required-check gate semantics. This Skill encodes PostHog's workflow-authoring conventions and the reasoning behind them so changes pass the linters and avoid known failure modes.

Core Features & Use Cases

  • Dispatch budget management: Fold small PR workflows into a single workflow_call parent and prefer trigger-level paths: filters to stay under the 500 runs/10s dispatch cap.
  • Concurrency and required-check gates: Apply the canonical per-PR concurrency block, per-SHA push grouping, and fail-closed always() gate jobs that allowlist every dependency result.
  • Checkout and caching optimization: Use sparse-checkout with cone mode off, bounded fetch-depth: 1000 plus blob:none for base diffs, and restore the master schema dump before running migrations.
  • Fork-safe secrets and tokens: Guard secret-needing steps with same-repo checks, use dedicated GitHub App tokens with || github.token fallback, and never run untrusted fork code with secrets.
  • Use Case: When adding a new CI workflow for a service, follow the new-workflow checklist covering triggers, concurrency, timeouts, SHA-pinned actions, runner choice, and fork handling, then verify with bin/hogli lint:workflows and actionlint.

Quick Start

Ask the assistant to create a new GitHub Actions workflow for your service following the authoring-ci-workflows conventions and checklist.

Frequently Asked Questions about authoring-ci-workflows

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new GitHub Actions workflow to a large monorepo?▼

Copy from a canonical existing workflow rather than writing from scratch, scope triggers with paths filters, add the canonical concurrency block, set timeout-minutes on every job, and pin third-party actions to full commit SHAs. Then run the workflow linters before pushing.

How do I avoid GitHub Actions rate limits and dispatch caps?▼

GitHub caps workflow dispatch at 500 runs per 10 seconds per repo, so minimize dispatched runs by folding small PR workflows into one workflow_call parent and using trigger-level paths filters. For API rate limits, use a dedicated GitHub App token instead of the shared GITHUB_TOKEN.

Should I use trigger paths filters or a paths-filter job in GitHub Actions?▼

Use trigger-level paths for workflows that are skippable as a whole, but never on a workflow whose check is required by branch protection, since a non-dispatched required check leaves PRs unmergeable. Required checks should fire on every PR and gate internally with a changes job.

How do I handle fork pull requests securely in a public repo?▼

Fork PR runs get a read-only GITHUB_TOKEN and no secrets, so guard secret-needing steps with a same-repo condition and degrade gracefully with a github.token fallback. Never check out and run fork code in pull_request_target workflows that have secret access.

Why is my GitHub Actions checkout step slow on a large repository?▼

On a repo with 45k files and 4.6 GiB of objects, what you materialize costs more than history depth. Use sparse-checkout with cone mode disabled to fetch only needed paths, and avoid filter blob:none unless paired with sparse-checkout to prevent slow lazy blob fetches.

When should I not use this workflow-authoring guidance?▼

This Skill covers authoring conventions, not debugging. For diagnosing red CI runs use a CI-debugging skill, for wiring a new secret end to end use a secrets-management skill, and for production deploy gating use the dedicated deploy-gating skill.

Related Skills

Explore More Software Engineering Skills→
githubgithub
38.5k

create-github-action-workflow-specification

Generate formal specifications for existing GitHub Actions CI/CD workflows.

Official
Intermediate
mvillmowmvillmow
18

fix-ci-failures

Diagnose CI failures by inspecting logs and reproducing issues locally.

Community
Advanced
bytetalentbytetalent

GitHub App vs OAuth App

Compare GitHub App and OAuth App for repository access decisions.

Official
Intermediate
HomericIntelligenceHomericIntelligence
18

validate-workflow

Validate GitHub Actions workflow files for syntax and best practices.

Official
Intermediate