apiVersion: devrunbook.io/v1alpha1
kind: Playbook
metadata:
  id: forge.gitea-best-practices
  slug: gitea-best-practices
  version: 1.0.0
  title: Gitea Repository Best-Practices Audit
  summary: Review metadata, branch and tag protection, templates, Actions and releases without changing Gitea.
  category: git-gitea
  tags:
  - gitea
  - git
  - governance
  lifecycle: reviewed
  riskTier: moderate
  authors:
  - name: DevRunbook Core Team
  license: MIT
package:
  files:
  - path: prompt.md
    role: template
    digest: true
    exportByDefault: false
  - path: README.md
    role: documentation
    digest: true
    exportByDefault: false
  - path: CHANGELOG.md
    role: changelog
    digest: true
    exportByDefault: false
  - path: examples/minimal.yaml
    role: example
    digest: true
    exportByDefault: false
  - path: evaluations/static-structure.yaml
    role: evaluation
    digest: true
    exportByDefault: false
spec:
  type: guided
  intent:
    problem: A Gitea repository can function while lacking governance, templates, protected branches, reproducible workflows
      or accurate release metadata.
    outcome: Produce an evidence-based read-only review of Gitea repository governance and a prioritized configuration plan.
    whenToUse:
    - When onboarding a repository to Gitea.
    - Before expanding collaboration or release automation.
    - When settings have grown organically.
    whenNotToUse:
    - When the task requires changing Gitea settings immediately.
    - When the token cannot read enough metadata for a meaningful review.
  modes:
  - inspect
  - plan
  defaultMode: inspect
  autonomy:
    min: observe
    max: plan
    default: diagnose
  inputs:
  - key: governanceDepth
    label: Governance depth
    description: Select which governance areas to inspect.
    type: multiselect
    required: true
    sensitive: false
    includeInOutput: true
    default:
    - branches
    - templates
    - actions
    - releases
    options:
    - metadata
    - branches
    - tags
    - permissions
    - templates
    - actions
    - releases
    - backup-mirroring
  - key: teamWorkflow
    label: Team workflow
    description: Describe how changes are normally proposed and approved.
    type: multiline
    required: false
    sensitive: false
    includeInOutput: true
    default: ''
  - key: publicRepository
    label: Public repository
    description: Indicate whether public contribution and disclosure concerns apply.
    type: boolean
    required: true
    sensitive: false
    includeInOutput: true
    default: false
  compatibility:
    repositoryRequired: true
    languages: []
    frameworks: []
    packageManagers: []
    databases: []
    deploymentTypes: []
    requiredProfileCapabilities: []
    incompatibleConditions: []
  guardrails:
  - id: read-only
    severity: blocking
    text: Do not create or change repository settings, branches, tags, issues, actions, secrets or releases.
  - id: capability-aware
    severity: blocking
    text: State when a finding is limited by Gitea version, token permission or unavailable API capability.
  - id: least-privilege
    severity: blocking
    text: Do not recommend admin-level access when repository-level read or write permissions are sufficient.
  - id: no-secret-content
    severity: blocking
    text: Do not read or report secret values from Actions or configuration.
  workflow:
  - id: capabilities
    title: Establish capabilities
    instruction: Record Gitea version, visible repository permissions and available evidence sources.
    required: true
  - id: metadata
    title: Review repository identity
    instruction: Review default branch, description, topics, license, README and archival state where selected.
    required: true
  - id: governance
    title: Review branch and tag governance
    instruction: Assess protection, direct push, review, status checks and release-tag controls where visible.
    required: true
  - id: workflow
    title: Review collaboration workflow
    instruction: Assess issue/PR templates, labels, contribution guidance and the stated team workflow.
    required: true
  - id: actions
    title: Review automation evidence
    instruction: Inspect visible workflow definitions, triggers, permissions and runner assumptions without exposing secrets.
    required: true
  - id: release
    title: Review release process
    instruction: Assess tags, releases, changelog, artifacts and rollback communication.
    required: true
  - id: plan
    title: Produce prioritized plan
    instruction: Separate settings changes, repository-file changes and optional future improvements.
    required: true
  validation:
    commandRoles: []
    checks:
    - id: no-writes
      type: assertion
      description: No Gitea write endpoint or repository modification was performed.
      blocking: true
      evidence: Integration request log or task report.
    - id: permission-limits
      type: artifact
      description: Unavailable or forbidden capabilities are listed.
      blocking: true
      evidence: Limitations section.
    - id: evidence
      type: artifact
      description: Each medium/high finding cites Gitea or repository evidence.
      blocking: true
      evidence: Finding table.
    - id: plan-separation
      type: artifact
      description: Recommendations distinguish Gitea settings from repository file changes.
      blocking: true
      evidence: Action plan.
  completion:
    criteria:
    - No Gitea or repository state was changed.
    - Governance findings include evidence and capability limitations.
    - Recommended settings fit the stated team workflow rather than generic policy.
    - A staged action plan identifies risk and required permission.
  failurePolicy:
    onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun
      the affected validation and report any genuine blocker without claiming success.
    onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve
      current behavior, document the decision needed and stop before an irreversible change.
    onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production
      behavior or validation results. Report what remains unavailable.
    onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe
      follow-up recommendation.
    onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report
      the blocked validation and do not claim the external path succeeded.
    onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes;
      provide the narrowest next diagnostic action.
  reporting:
    sections:
    - id: context
      title: Repository and capability context
      required: true
      description: Gitea version, visible permissions and workflow assumptions.
    - id: findings
      title: Governance findings
      required: true
      description: Evidence-based findings by metadata, branch/tag policy, collaboration, Actions and releases.
    - id: plan
      title: Prioritized implementation plan
      required: true
      description: Staged actions, required permissions and suggested playbooks.
    - id: limitations
      title: Limitations
      required: true
      description: Unavailable APIs, permission constraints and unverified settings.
  template:
    main: prompt.md
    partials: []
  exports:
    prompt: true
    markdown: true
    runPack: true
    agentsSuggestion: true
quality:
  reviewStatus: technical-reviewed
  testedStacks: []
  knownLimitations:
  - Open-source and Enterprise editions can expose different governance capabilities.
  - API visibility may not reflect settings the token cannot access.
  evaluationCaseIds:
  - gitea-best-practices.static-structure