Copilot Instructions for Codespace Features Repository

This repository contains devcontainer features to assist teams in adopting GitHub Codespaces. Features are reusable "plugins" that can be installed into devcontainers to add tools, languages, or services.

Repository Structure

Core Components

```
/src/
```
- Contains all feature implementations, each in its own subdirectory
```
/test/
```
- Contains test scenarios for each feature, plus global integration tests
```
/.github/workflows/
```
- CI/CD automation for testing and releasing features

Feature Structure

Each feature in

/src/{feature-name}/

contains:

```
devcontainer-feature.json
```
- Feature metadata, options, and configuration
```
install.sh
```
- Installation script (main implementation)
```
README.md
```
- Feature documentation (auto-generated, do not edit manually)
Optional:
```
NOTES.md
```
- Implementation notes that get included in README.md generation (auto-generated, do not edit manually)

Testing Structure

```
/test/{feature-name}/
```
- Feature-specific tests with
```
scenarios.json
```
and test scripts
```
/test/_global/
```
- Integration tests that test multiple features together
Test scenarios are defined in
```
scenarios.json
```
files and executed using the devcontainer CLI

Current Features

Feature	Description
`artifacts-helper`	Azure Artifacts credential helper for Codespace authentication
`devtool`	Microsoft DevTool (internal only)
`docfx`	DocFX documentation generation tool
`external-repository`	Handles external git repository integration in Codespaces
`go`	Go language with Mariner Linux support
`microsoft-git`	Microsoft's Git distribution with Scalar and GVFS

Development Guidelines

Semantic Versioning

Features use semantic versioning (SemVer):

MAJOR version for incompatible API changes
MINOR version for backward-compatible functionality additions
PATCH version for backward-compatible bug fixes

When making changes to a feature:

Update the
```
version
```
field in
```
devcontainer-feature.json
```
Follow SemVer guidelines based on the type of change
Document breaking changes in the feature description or NOTES.md

Creating a New Feature

Create directory structure:
```
/src/{feature-name}/
```

Write

devcontainer-feature.json

with proper metadata:

{
  "id": "feature-name",
  "version": "1.0.0",
  "name": "Feature Display Name",
  "description": "Brief description",
  "options": { /* configuration options */ },
  "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
}

Implement
```
install.sh
```
with proper error handling and logging
Create comprehensive tests in
```
/test/{feature-name}/
```

Feature Implementation Best Practices

Error Handling: Always check exit codes and handle failures gracefully
Logging: Use consistent logging format with feature name and version
Idempotency: Features should handle multiple installations safely
Cross-Platform: Test on Ubuntu, Debian, and Mariner Linux base images
Dependencies: Use
```
installsAfter
```
for proper installation order

Testing Requirements

Create
```
scenarios.json
```
with comprehensive test cases
Test on multiple base images: Ubuntu, Debian, Mariner
Include edge cases: version conflicts, reinstallation, error conditions
Use descriptive test names that explain what is being validated

Test Execution

# Test single feature on specific base image
devcontainer features test -f {feature-name} -i {base-image} .

# Test feature autogenerated scenarios only (CI pattern)
devcontainer features test --skip-scenarios -f {feature-name} -i {base-image} .

# Test feature custom scenarios only (CI pattern)
devcontainer features test -f {feature-name} --skip-autogenerated .

# Test all global scenarios
devcontainer features test --global-scenarios-only .

# Common base images used in CI
# - mcr.microsoft.com/devcontainers/base:ubuntu
# - mcr.microsoft.com/devcontainers/base:debian  
# - mcr.microsoft.com/cbl-mariner/base/core:2.0

CI/CD Workflows

Automated Testing

```
test-pr.yaml
```
- Tests changed features on pull requests using path filtering
```
test-all.yaml
```
- Comprehensive testing on main branch across all features
Tests run on Ubuntu, Debian, and Mariner base images automatically
Separate jobs for autogenerated tests and custom scenarios

Release Process

```
release.yaml
```
- Publishes features to GitHub Container Registry
Features are versioned using semantic versioning
Each feature is published independently

Code Quality Standards

Shell Script Guidelines

Use
```
set -e
```
for error handling
Quote variables properly:
```
"${VARIABLE}"
```
Check for required tools before using them
Provide meaningful error messages
Follow consistent indentation and formatting

JSON Configuration

Use proper JSON validation
Follow devcontainer feature schema
Include comprehensive option descriptions
Specify version constraints clearly

Common Patterns

Package Installation

# Check for package manager
if command -v apt-get >/dev/null 2>&1; then
    package_manager="apt"
elif command -v tdnf >/dev/null 2>&1; then
    package_manager="tdnf"
fi

Version Detection

# Auto-detect latest version
if [ "${VERSION}" = "latest" ] || [ "${VERSION}" = "lts" ]; then
    VERSION=$(curl -s API_ENDPOINT | jq -r .tag_name | sed 's/^v//')
fi

Cross-Platform Compatibility

Test on Ubuntu (apt), Debian (apt), and Mariner (tdnf)
Handle different package names across distributions
Account for different default paths and permissions

Debugging and Troubleshooting

Common Issues

Network timeouts: Features may fail in environments with restricted internet
Package conflicts: Check for existing installations before proceeding
Permission issues: Ensure proper file permissions and user context
Path problems: Verify PATH updates and binary locations

Debugging Tools

Check feature logs in devcontainer build output
Test locally using devcontainer CLI
Use
```
docker exec
```
to inspect container state
Review GitHub Actions logs for CI failures

Security Considerations

Best Practices

Validate all input parameters
Use secure download methods (HTTPS, signature verification)
Avoid hardcoded credentials or secrets
Follow principle of least privilege
Pin dependency versions for reproducibility

Secrets and Credentials

Use devcontainer secrets for sensitive data
Never commit credentials to the repository
Support both build-time and runtime authentication methods

Contributing Guidelines

Pull Request Process

Create feature branch from
```
main
```
Implement feature with comprehensive tests
Update the
```
version
```
field in
```
devcontainer-feature.json
```
following semantic versioning
Ensure all CI checks pass
Update documentation as needed
Request review from maintainers

Code Review Checklist

Feature follows repository conventions
Tests cover success and failure scenarios
Cross-platform compatibility verified
Security best practices followed
Documentation is complete and accurate

Support and Resources

When working on this repository, focus on creating reliable, cross-platform features that enhance the Codespaces development experience while following established patterns and best practices.

Copilot Instructions for Codespace Features Repository

Repository Structure

Core Components

```
/src/
```
- Contains all feature implementations, each in its own subdirectory
```
/test/
```
- Contains test scenarios for each feature, plus global integration tests
```
/.github/workflows/
```
- CI/CD automation for testing and releasing features

Feature Structure

Each feature in

/src/{feature-name}/

contains:

```
devcontainer-feature.json
```
- Feature metadata, options, and configuration
```
install.sh
```
- Installation script (main implementation)
```
README.md
```
- Feature documentation (auto-generated, do not edit manually)
Optional:
```
NOTES.md
```
- Implementation notes that get included in README.md generation (auto-generated, do not edit manually)

Testing Structure

```
/test/{feature-name}/
```
- Feature-specific tests with
```
scenarios.json
```
and test scripts
```
/test/_global/
```
- Integration tests that test multiple features together
Test scenarios are defined in
```
scenarios.json
```
files and executed using the devcontainer CLI

Current Features

Feature	Description
`artifacts-helper`	Azure Artifacts credential helper for Codespace authentication
`devtool`	Microsoft DevTool (internal only)
`docfx`	DocFX documentation generation tool
`external-repository`	Handles external git repository integration in Codespaces
`go`	Go language with Mariner Linux support
`microsoft-git`	Microsoft's Git distribution with Scalar and GVFS

Development Guidelines

Semantic Versioning

Features use semantic versioning (SemVer):

MAJOR version for incompatible API changes
MINOR version for backward-compatible functionality additions
PATCH version for backward-compatible bug fixes

When making changes to a feature:

Update the
```
version
```
field in
```
devcontainer-feature.json
```
Follow SemVer guidelines based on the type of change
Document breaking changes in the feature description or NOTES.md

Creating a New Feature

Create directory structure:
```
/src/{feature-name}/
```

Write

devcontainer-feature.json

with proper metadata:

{
  "id": "feature-name",
  "version": "1.0.0",
  "name": "Feature Display Name",
  "description": "Brief description",
  "options": { /* configuration options */ },
  "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
}

Implement
```
install.sh
```
with proper error handling and logging
Create comprehensive tests in
```
/test/{feature-name}/
```

Feature Implementation Best Practices

Error Handling: Always check exit codes and handle failures gracefully
Logging: Use consistent logging format with feature name and version
Idempotency: Features should handle multiple installations safely
Cross-Platform: Test on Ubuntu, Debian, and Mariner Linux base images
Dependencies: Use
```
installsAfter
```
for proper installation order

Testing Requirements

Create
```
scenarios.json
```
with comprehensive test cases
Test on multiple base images: Ubuntu, Debian, Mariner
Include edge cases: version conflicts, reinstallation, error conditions
Use descriptive test names that explain what is being validated

Test Execution

# Test single feature on specific base image
devcontainer features test -f {feature-name} -i {base-image} .

# Test feature autogenerated scenarios only (CI pattern)
devcontainer features test --skip-scenarios -f {feature-name} -i {base-image} .

# Test feature custom scenarios only (CI pattern)
devcontainer features test -f {feature-name} --skip-autogenerated .

# Test all global scenarios
devcontainer features test --global-scenarios-only .

# Common base images used in CI
# - mcr.microsoft.com/devcontainers/base:ubuntu
# - mcr.microsoft.com/devcontainers/base:debian  
# - mcr.microsoft.com/cbl-mariner/base/core:2.0

CI/CD Workflows

Automated Testing

```
test-pr.yaml
```
- Tests changed features on pull requests using path filtering
```
test-all.yaml
```
- Comprehensive testing on main branch across all features
Tests run on Ubuntu, Debian, and Mariner base images automatically
Separate jobs for autogenerated tests and custom scenarios

Release Process

```
release.yaml
```
- Publishes features to GitHub Container Registry
Features are versioned using semantic versioning
Each feature is published independently

Code Quality Standards

Shell Script Guidelines

Use
```
set -e
```
for error handling
Quote variables properly:
```
"${VARIABLE}"
```
Check for required tools before using them
Provide meaningful error messages
Follow consistent indentation and formatting

JSON Configuration

Use proper JSON validation
Follow devcontainer feature schema
Include comprehensive option descriptions
Specify version constraints clearly

Common Patterns

Package Installation

# Check for package manager
if command -v apt-get >/dev/null 2>&1; then
    package_manager="apt"
elif command -v tdnf >/dev/null 2>&1; then
    package_manager="tdnf"
fi

Version Detection

# Auto-detect latest version
if [ "${VERSION}" = "latest" ] || [ "${VERSION}" = "lts" ]; then
    VERSION=$(curl -s API_ENDPOINT | jq -r .tag_name | sed 's/^v//')
fi

Cross-Platform Compatibility

Test on Ubuntu (apt), Debian (apt), and Mariner (tdnf)
Handle different package names across distributions
Account for different default paths and permissions

Debugging and Troubleshooting

Common Issues

Network timeouts: Features may fail in environments with restricted internet
Package conflicts: Check for existing installations before proceeding
Permission issues: Ensure proper file permissions and user context
Path problems: Verify PATH updates and binary locations

Debugging Tools

Check feature logs in devcontainer build output
Test locally using devcontainer CLI
Use
```
docker exec
```
to inspect container state
Review GitHub Actions logs for CI failures

Security Considerations

Best Practices

Validate all input parameters
Use secure download methods (HTTPS, signature verification)
Avoid hardcoded credentials or secrets
Follow principle of least privilege
Pin dependency versions for reproducibility

Secrets and Credentials

Use devcontainer secrets for sensitive data
Never commit credentials to the repository
Support both build-time and runtime authentication methods

Contributing Guidelines

Pull Request Process

Create feature branch from
```
main
```
Implement feature with comprehensive tests
Update the
```
version
```
field in
```
devcontainer-feature.json
```
following semantic versioning
Ensure all CI checks pass
Update documentation as needed
Request review from maintainers

Code Review Checklist

Feature follows repository conventions
Tests cover success and failure scenarios
Cross-platform compatibility verified
Security best practices followed
Documentation is complete and accurate

Support and Resources

When working on this repository, focus on creating reliable, cross-platform features that enhance the Codespaces development experience while following established patterns and best practices.

Copilot Instructions for Codespace Features Repository

Related Skills

Nano Banana Pro

Markdown Converter

1password