Git Registry
This example shows how to use a Git repository as a PromptScript registry for sharing configurations across teams.
Use Cases
- Central registry - Share organization-wide standards via Git
- Version control - Pin to specific versions using Git tags
- Access control - Use GitHub/GitLab permissions for registry access
- CI/CD integration - Automatic updates on registry changes
Basic Setup
Public Repository
id: my-projectsyntax: '1.4.0'
input: entry: .promptscript/project.prs
registry: git: url: https://github.com/your-org/promptscript-registry.git ref: main
targets: - github - claudePrivate Repository with Token
id: my-projectsyntax: '1.4.0'
input: entry: .promptscript/project.prs
registry: git: url: https://github.com/your-org/private-registry.git ref: main auth: type: token tokenEnvVar: GITHUB_TOKEN cache: enabled: true ttl: 3600000 # 1 hour in milliseconds
targets: - github - claudeSSH Authentication
id: my-projectsyntax: '1.4.0'
input: entry: .promptscript/project.prs
registry: git: ref: main auth: type: ssh sshKeyPath: ~/.ssh/id_ed25519
targets: - github - claudeSelf-Hosted Git Servers
PromptScript works with any Git server, not just GitHub. This includes self-hosted GitLab, Gitea, Bitbucket Server, Azure DevOps, and other Git-compatible servers.
Self-Hosted GitLab
id: my-projectsyntax: '1.4.0'
input: entry: .promptscript/project.prs
registry: git: url: https://gitlab.your-company.com/org/promptscript-registry.git ref: main auth: type: token tokenEnvVar: GITLAB_TOKEN # Use any env var name you prefer
targets: - github - claude# Set your GitLab Personal Access Token (requires read_repository scope)export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"prs pullSelf-Hosted GitLab with SSH
registry: git: ref: main auth: type: ssh sshKeyPath: ~/.ssh/id_ed25519Gitea / Forgejo
registry: git: url: https://gitea.your-company.com/org/promptscript-registry.git ref: main auth: type: token tokenEnvVar: GITEA_TOKENBitbucket Server (Self-Hosted)
registry: git: url: https://bitbucket.your-company.com/scm/org/promptscript-registry.git ref: main auth: type: token tokenEnvVar: BITBUCKET_TOKENAzure DevOps Server
registry: git: url: https://dev.your-company.com/org/project/_git/promptscript-registry ref: main auth: type: token tokenEnvVar: AZURE_DEVOPS_TOKENToken Types by Provider
| Provider | Token Type | Required Scope |
|---|---|---|
| GitLab | Personal Access Token | read_repository |
| GitLab | Project Access Token | read_repository |
| GitLab | Deploy Token | read_repository |
| Gitea | Access Token | read:repository |
| Bitbucket Server | HTTP Access Token | Repository read |
| Azure DevOps | Personal Access Token | Code (Read) |
Environment Variable Naming
The tokenEnvVar field accepts any environment variable name. Use a name that makes sense for your organization, such as REGISTRY_TOKEN, GITLAB_TOKEN, or GIT_REGISTRY_PAT.
Version Pinning
Pin to Specific Tag
registry: git: url: https://github.com/your-org/promptscript-registry.git ref: v1.2.0 # Pin to release v1.2.0Pin in .prs Files
You can also pin specific imports to versions:
@meta { id: "my-project" syntax: "1.0.0"}
# Pin to specific version (in a multi-file setup):
# Use latest from configured ref:@use @company/security as secRepository Structure
Recommended structure for a Git registry:
promptscript-registry/├── README.md├── CHANGELOG.md├── @org/│ ├── base.prs # Organization base│ ├── security.prs # Security policies│ └── compliance.prs # Compliance rules├── @teams/│ ├── frontend.prs # Frontend team config│ ├── backend.prs # Backend team config│ └── mobile.prs # Mobile team config└── @fragments/ ├── testing.prs # Reusable testing rules └── documentation.prs # Documentation standardsCLI Commands
Pull from Registry
# Pull using default branch from configprs pull
# Pull from specific branchprs pull --branch develop
# Pull from specific tagprs pull --tag v1.0.0
# Pull from specific commitprs pull --commit abc123def
# Force refresh (ignore cache)prs pull --refresh
# Preview without pullingprs pull --dry-runCI/CD Integration
GitHub Actions
name: PromptScript CI
on: push: paths: - '.promptscript/**' - 'promptscript.yaml'
jobs: compile: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- uses: actions/setup-node@v4 with: node-version: '24'
- name: Install PromptScript run: npm install -g @promptscript/cli
- name: Pull registry updates run: prs pull env: GITHUB_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
- name: Compile run: prs compile
- name: Check for changes run: | git diff --exit-code || { echo "::error::Compiled files changed. Run 'prs compile' locally." exit 1 }GitLab CI
promptscript: image: node:22 script: - npm install -g @promptscript/cli - prs pull - prs compile - git diff --exit-code variables: # Use GITLAB_TOKEN for GitLab registries, or match your tokenEnvVar config GITLAB_TOKEN: $REGISTRY_TOKEN only: changes: - .promptscript/**/* - promptscript.yamlSelf-Hosted GitLab CI
For self-hosted GitLab, you can use the built-in CI_JOB_TOKEN for repositories within the same GitLab instance:
```yamlvariables: GITLAB_TOKEN: $CI_JOB_TOKEN```
For cross-instance access, use a Project Access Token or Deploy Token stored in CI/CD variables.Complete Example
Registry Files
@org/base.prs
@meta { id: "@org/base" syntax: "1.0.0" org: "ACME Corp"}
@identity { """ You are an AI assistant at ACME Corp. Follow our coding standards and best practices. """}
@standards { code: [ "Code review required for all changes", "Tests required for all code" ] git: [ "Use conventional commits format" ]}
@restrictions { - "Never commit secrets" - "Always follow security policies"}@teams/frontend.prs
@meta { id: "@teams/frontend" syntax: "1.0.0"}
# In a multi-file setup, you would inherit:@inherit @org/base
@identity { """ You are a frontend development expert. Expertise: React, TypeScript, TailwindCSS """}
@context { framework: "React 18" language: "TypeScript 5" styling: "TailwindCSS"}Project Configuration
promptscript.yaml
id: customer-portalsyntax: '1.4.0'
inherit: '@teams/frontend'
input: entry: .promptscript/project.prs
registry: git: url: https://github.com/acme/promptscript-registry.git ref: v1.0.0 auth: type: token tokenEnvVar: GITHUB_TOKEN cache: enabled: true ttl: 3600000
targets: - github - claude - cursor.promptscript/project.prs
@meta { id: "customer-portal" syntax: "1.0.0"}
# In a multi-file setup, you would inherit:
@context { project: "Customer Portal"
""" Self-service portal for ACME customers. Features: account management, orders, support. """}
@shortcuts { "/portal": "Work on portal features"}Alias-Based Import Workflow
1. Configure Aliases
Add aliases to promptscript.yaml once:
id: customer-portalsyntax: '1.4.0'
registries: '@company': github.com/acme/promptscript-base '@team': github.com/acme/team-frontend
registry: git: url: https://github.com/acme/promptscript-base.git ref: main auth: type: token tokenEnvVar: GITHUB_TOKEN
targets: - github - claude2. Use Aliases in .prs Files
@meta { id: "customer-portal" syntax: "1.0.0"}
# Inherit from company base — resolves to github.com/acme/promptscript-base/base.prs@inherit @company/base
# Team-specific standards@use @team/stacks/react
# Pin to a specific release3. Compile
prs compilePromptScript expands @company to github.com/acme/promptscript-base, clones (or uses cache), resolves the file path, and compiles.
URL Import Example
URL imports work without any alias configuration:
@meta { id: "my-project" syntax: "1.0.0"}
# Direct URL import — no alias needed@use github.com/acme/shared-standards/fragments/security
# Open-source skill auto-discovered from SKILL.md@use github.com/some-org/claude-skills/skills/tdd-workflow
# Versioned URL importDebug the resolution chain with:
prs resolve github.com/acme/shared-standards/@fragments/securityLockfile Workflow
Initial Setup
# 1. Add remote imports to your .prs files, then lock:prs lock
# 2. Commit the lockfilegit add promptscript.lockgit commit -m "chore: add PromptScript lockfile"Checking for Updates
# See what would change without updatingprs update --dry-run
# Update a specific packageprs update github.com/acme/promptscript-base
# Update all packages and commitprs updategit add promptscript.lockgit commit -m "chore(deps): update PromptScript dependencies"Verifying in CI
# Fail if lockfile is not up to dateprs lock --dry-runCI Pipeline Example with Vendor
This example uses vendor mode so CI never needs network access to the registry.
Local Setup (run once or on updates)
# Sync vendor from the lockfileprs vendor sync
# Commit vendor directory and lockfilegit add .promptscript/vendor promptscript.lockgit commit -m "chore: vendor PromptScript dependencies"GitHub Actions Pipeline
name: PromptScript CI
on: push: paths: - '.promptscript/**' - 'promptscript.yaml' - 'promptscript.lock'
jobs: compile: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- uses: actions/setup-node@v4 with: node-version: '24'
- name: Install PromptScript run: npm install -g @promptscript/cli
- name: Check vendor is in sync run: prs vendor check
- name: Validate run: prs validate --strict
- name: Compile run: prs compile
- name: Check for uncommitted changes run: | git diff --exit-code || { echo "::error::Compiled files are out of date. Run 'prs compile' locally." exit 1 }GitLab CI Pipeline
promptscript: image: node:22 script: - npm install -g @promptscript/cli - prs vendor check - prs validate --strict - prs compile - git diff --exit-code only: changes: - .promptscript/**/* - promptscript.yaml - promptscript.lockTroubleshooting
Authentication Failed
Error: Git authentication failedSolutions:
- Check your token environment variable is set:
echo $GITLAB_TOKEN(or your configuredtokenEnvVar) - Verify token has the required scope:
- GitHub:
reposcope - GitLab:
read_repositoryscope - Gitea:
read:repositoryscope
- GitHub:
- For SSH, ensure key is added:
ssh-add -l - For self-hosted servers, verify the URL is correct and accessible from your network
Ref Not Found
Error: Git ref not found: v2.0.0Solutions:
- List available tags:
git ls-remote --tags <url> - Use existing branch/tag
- Check for typos in version
Cache Issues
# Force refresh to bypass cacheprs pull --refreshBest Practices
- Version your registry - Use semantic versioning with Git tags
- Pin production versions - Don’t use
mainin production - Document changes - Maintain a CHANGELOG.md
- Test before releasing - Validate all .prs files before tagging
- Use short TTL in dev - Faster iteration with
ttl: 60000