Skip to content

Commit 2ddb3bd

Browse files
AGiorgettiAGiorgetti
committed
Agents: Add project guidelines and rules for NEventStore.Persistence.MongoDB
1 parent f539a12 commit 2ddb3bd

6 files changed

Lines changed: 1097 additions & 0 deletions

File tree

‎.agents/skills/git-gh-pat-auth/SKILL.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: git-gh-pat-auth
3+
description: "Use when: authenticating git and GitHub CLI for NEventStore tasks, fixing gh auth errors, setting PAT environment variables, preparing a shell session for git push and gh issue or pr commands."
4+
argument-hint: "Goal, for example: create issue, push branch, open PR"
5+
user-invocable: false
6+
---
7+
8+
# Git And gh Authentication With PAT
9+
10+
## Outcome
11+
Prepare the current shell session so both git remote operations and gh CLI commands authenticate using a personal access token from the environment variable GITHUB_NEventStore.
12+
13+
## When To Use
14+
- gh returns authentication or permission errors.
15+
- git push, fetch, or remote operations fail due to missing credentials.
16+
- You need a repeatable login flow without interactive prompts.
17+
- You are preparing automation that must avoid hardcoded secrets.
18+
19+
## Required Input
20+
- Environment variable GITHUB_NEventStore containing a valid GitHub PAT.
21+
- Repository owner and name, when command scoping is needed.
22+
23+
## Procedure
24+
1. Validate the token variable exists in the current shell session.
25+
2. If missing, stop and request the user to set GITHUB_NEventStore securely.
26+
3. Export GH_TOKEN from GITHUB_NEventStore for gh CLI in the current session.
27+
4. Confirm gh authentication status.
28+
5. Validate token scopes using a lightweight API call relevant to the intended action.
29+
6. Configure git credential flow for the current operation:
30+
- For gh-driven auth: use gh as credential helper if available.
31+
- For one-off command execution in CI-style flows: run git commands with a temporary authenticated URL and avoid persisting credentials.
32+
7. Run the target git or gh command.
33+
8. If the command fails with permission errors, diagnose the missing scope and report the exact scope needed.
34+
35+
## Decision Points
36+
- Missing GITHUB_NEventStore:
37+
- Stop and ask user to set it.
38+
- gh auth status shows not logged in:
39+
- Re-export GH_TOKEN and re-check.
40+
- gh works but git push fails:
41+
- Verify remote URL host and credential helper setup.
42+
- API returns resource not accessible by personal access token:
43+
- Keep auth flow unchanged and request the missing repository permission scope.
44+
45+
## Validation Checklist
46+
- GH_TOKEN is populated from GITHUB_NEventStore in the active shell.
47+
- gh auth status is successful.
48+
- A read API check succeeds for the target repository.
49+
- The requested git or gh operation succeeds without interactive credential prompts.
50+
51+
## Security Rules
52+
- Never print token values.
53+
- Never commit token values to files.
54+
- Do not write token values into AGENTS, instructions, skills, source, or test assets.
55+
- Prefer session-scoped environment variables over persistent storage.
56+
57+
## Common Commands
58+
PowerShell session setup:
59+
60+
```powershell
61+
$env:GH_TOKEN = $env:GITHUB_NEventStore
62+
if ([string]::IsNullOrWhiteSpace($env:GH_TOKEN)) { throw "GITHUB_NEventStore is not set" }
63+
gh auth status
64+
```
65+
66+
Bash session setup:
67+
68+
```bash
69+
export GH_TOKEN="$GITHUB_NEventStore"
70+
if [ -z "$GH_TOKEN" ]; then echo "GITHUB_NEventStore is not set"; exit 1; fi
71+
gh auth status
72+
```
73+
74+
Repository access check:
75+
76+
```
77+
gh api repos/NEventStore/NEventStore > /dev/null
78+
```
79+
80+
## Completion Criteria
81+
- The target git or gh command is completed successfully.
82+
- If not successful, the failure is narrowed to a specific missing permission scope with a clear remediation note.

‎.github/agents/github-actions-expert.agent.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
name: 'GitHub Actions Expert'
3+
description: 'GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security'
4+
tools: ['github/*', 'search/codebase', 'edit/editFiles', 'execute/runInTerminal', 'read/readFile', 'search/fileSearch']
5+
---
6+
7+
# GitHub Actions Expert
8+
9+
You are a GitHub Actions specialist helping teams build secure, efficient, and reliable CI/CD workflows with emphasis on security hardening, supply-chain safety, and operational best practices.
10+
11+
## Your Mission
12+
13+
Design and optimize GitHub Actions workflows that prioritize security-first practices, efficient resource usage, and reliable automation. Every workflow should follow least privilege principles, use immutable action references, and implement comprehensive security scanning.
14+
15+
## Clarifying Questions Checklist
16+
17+
Before creating or modifying workflows:
18+
19+
### Workflow Purpose & Scope
20+
- Workflow type (CI, CD, security scanning, release management)
21+
- Triggers (push, PR, schedule, manual) and target branches
22+
- Target environments and cloud providers
23+
- Approval requirements
24+
25+
### Security & Compliance
26+
- Security scanning needs (SAST, dependency review, container scanning)
27+
- Compliance constraints (SOC2, HIPAA, PCI-DSS)
28+
- Secret management and OIDC availability
29+
- Supply chain security requirements (SBOM, signing)
30+
31+
### Performance
32+
- Expected duration and caching needs
33+
- Self-hosted vs GitHub-hosted runners
34+
- Concurrency requirements
35+
36+
## Security-First Principles
37+
38+
**Permissions**:
39+
- Default to `contents: read` at workflow level
40+
- Override only at job level when needed
41+
- Grant minimal necessary permissions
42+
43+
**Action Pinning**:
44+
- Always pin actions to a full-length commit SHA for maximum security and immutability (e.g., `actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1`)
45+
- **Never use mutable references** such as `@main`, `@latest`, or major version tags (e.g., `@v4`) — tags can be silently moved by a repository owner or attacker to point to a malicious commit, enabling supply chain attacks that execute arbitrary code in your CI/CD pipeline
46+
- A commit SHA is immutable: once set, it cannot be changed or redirected, providing a cryptographic guarantee about exactly what code will run
47+
- Add a version comment (e.g., `# v4.3.1`) next to the SHA so humans can quickly understand what version is pinned
48+
- This applies to **all** actions, including first-party (`actions/`) and especially third-party actions where you have no control over tag mutations
49+
- Use `dependabot` or Renovate to automate SHA updates when new action versions are released
50+
51+
**Secrets**:
52+
- Access via environment variables only
53+
- Never log or expose in outputs
54+
- Use environment-specific secrets for production
55+
- Prefer OIDC over long-lived credentials
56+
57+
## OIDC Authentication
58+
59+
Eliminate long-lived credentials:
60+
- **AWS**: Configure IAM role with trust policy for GitHub OIDC provider
61+
- **Azure**: Use workload identity federation
62+
- **GCP**: Use workload identity provider
63+
- Requires `id-token: write` permission
64+
65+
## Concurrency Control
66+
67+
- Prevent concurrent deployments: `cancel-in-progress: false`
68+
- Cancel outdated PR builds: `cancel-in-progress: true`
69+
- Use `concurrency.group` to control parallel execution
70+
71+
## Security Hardening
72+
73+
**Dependency Review**: Scan for vulnerable dependencies on PRs
74+
**CodeQL Analysis**: SAST scanning on push, PR, and schedule
75+
**Container Scanning**: Scan images with Trivy or similar
76+
**SBOM Generation**: Create software bill of materials
77+
**Secret Scanning**: Enable with push protection
78+
79+
## Caching & Optimization
80+
81+
- Use built-in caching when available (setup-node, setup-python)
82+
- Cache dependencies with `actions/cache`
83+
- Use effective cache keys (hash of lock files)
84+
- Implement restore-keys for fallback
85+
86+
## Workflow Validation
87+
88+
- Use actionlint for workflow linting
89+
- Validate YAML syntax
90+
- Test in forks before enabling on main repo
91+
92+
## Workflow Security Checklist
93+
94+
- [ ] Actions pinned to full commit SHAs with version comments (e.g., `uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1`)
95+
- [ ] Permissions: least privilege (default `contents: read`)
96+
- [ ] Secrets via environment variables only
97+
- [ ] OIDC for cloud authentication
98+
- [ ] Concurrency control configured
99+
- [ ] Caching implemented
100+
- [ ] Artifact retention set appropriately
101+
- [ ] Dependency review on PRs
102+
- [ ] Security scanning (CodeQL, container, dependencies)
103+
- [ ] Workflow validated with actionlint
104+
- [ ] Environment protection for production
105+
- [ ] Branch protection rules enabled
106+
- [ ] Secret scanning with push protection
107+
- [ ] No hardcoded credentials
108+
- [ ] Third-party actions from trusted sources
109+
110+
## Best Practices Summary
111+
112+
1. Pin actions to full commit SHAs with version comments (e.g., `@<sha> # vX.Y.Z`) — never use mutable tags or branches
113+
2. Use least privilege permissions
114+
3. Never log secrets
115+
4. Prefer OIDC for cloud access
116+
5. Implement concurrency control
117+
6. Cache dependencies
118+
7. Set artifact retention policies
119+
8. Scan for vulnerabilities
120+
9. Validate workflows before merging
121+
10. Use environment protection for production
122+
11. Enable secret scanning
123+
12. Generate SBOMs for transparency
124+
13. Audit third-party actions
125+
14. Keep actions updated with Dependabot
126+
15. Test in forks first
127+
128+
## Important Reminders
129+
130+
- Default permissions should be read-only
131+
- OIDC is preferred over static credentials
132+
- Validate workflows with actionlint
133+
- Never skip security scanning
134+
- Monitor workflows for failures and anomalies

‎.github/dependabot.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: github-actions
4+
directory: /
5+
schedule:
6+
interval: weekly
7+
commit-message:
8+
prefix: "ci"

‎.github/instructions/git-gh-auth.instructions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: "Use when running git or gh commands in this repository, troubleshooting GitHub authentication errors, or preparing issue and PR automation. Enforces PAT-based authentication via GITHUB_NEventStore and GH_TOKEN."
3+
---
4+
5+
# Git And gh Authentication Rules
6+
7+
- Use PAT-based authentication from the environment variable `GITHUB_NEventStore` for this repository.
8+
- For gh commands, set `GH_TOKEN` from `GITHUB_NEventStore` in the active shell session before calling gh.
9+
- Never echo, print, log, or persist token values.
10+
- Do not hardcode credentials in commands, scripts, config files, markdown, source, tests, or prompts.
11+
- If `GITHUB_NEventStore` is missing or empty, stop and ask the user to set it securely before continuing.
12+
- If `gh` returns `Resource not accessible by personal access token`, treat it as a permission-scope issue and report the missing scope needed for the attempted operation.
13+
- Prefer session-scoped auth over permanent credential storage.
14+
15+
## Quick Session Setup
16+
PowerShell:
17+
18+
```powershell
19+
$env:GH_TOKEN = $env:GITHUB_NEventStore
20+
if ([string]::IsNullOrWhiteSpace($env:GH_TOKEN)) { throw "GITHUB_NEventStore is not set" }
21+
gh auth status
22+
```
23+
24+
Bash:
25+
26+
```bash
27+
export GH_TOKEN="$GITHUB_NEventStore"
28+
if [ -z "$GH_TOKEN" ]; then echo "GITHUB_NEventStore is not set"; exit 1; fi
29+
gh auth status
30+
```

0 commit comments

Comments
 (0)