|
|
|
@@ -0,0 +1,226 @@
|
|
|
|
|
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
|
DevRunbook release export