# Deploy Keys for Publishing Packages

This document explains how to set up and use deploy keys for publishing packages to the Generation One Gitea repository.

## What are Deploy Keys?

Deploy keys are SSH keys that grant access to a specific repository. They are more secure than personal access tokens because:

1. They can be limited to a single repository
2. They can be read-only or read-write
3. They don't grant access to your personal account

## Setting Up Deploy Keys

### 1. Generate a Deploy Key

Run the provided script to generate a new deploy key:

```bash
# Make the script executable
chmod +x scripts/setup-deploy-key.sh

# Run the script
./scripts/setup-deploy-key.sh
```

This will:
- Generate a new SSH key pair (`.deploy-key` and `.deploy-key.pub`)
- Add the public key to the Gitea repository as a deploy key

### 2. Create a Gitea Token

1. Log in to https://git.generation.one
2. Go to your user settings (click your profile picture)
3. Select "Applications" or "Access Tokens"
4. Create a new token with the "packages:write" scope
5. Save the token to a file named `.gitea-token` in the root of the repository

## Creating New Packages

### Setting the Initial Version

When creating a new package, you can set the initial version in the `package.json` file:

```json
{
  "name": "@g1/your-package-name",
  "version": "0.2.0",
  "description": "Your package description",
  ...
}
```

Choosing a version like `0.2.0` for a new package is a good practice as it indicates:
- The package is still in development (0.x.x)
- It has gone through some initial development (0.2.x rather than 0.1.x)
- It's starting with a clean minor version (x.x.0)

## Publishing Packages

### Manual Publishing

Use the provided script to publish a package:

```bash
# Make the script executable
chmod +x scripts/publish-package.sh

# Publish a package with a patch version bump
./scripts/publish-package.sh packages/sse-client patch

# Publish a package with a specific version
./scripts/publish-package.sh packages/sse-client version:0.2.0

# Publish a package without changing the version
./scripts/publish-package.sh packages/sse-client none
```

### Automated Publishing with GitHub Actions

A GitHub Actions workflow is included in this repository for automated publishing:

1. Go to the "Actions" tab in your GitHub repository
2. Select the "Publish Package" workflow
3. Click "Run workflow"
4. Enter the package directory (e.g., `packages/sse-client`)
5. Select the version bump type (patch, minor, major, or none)
6. Click "Run workflow"

### Setting Up GitHub Actions Secrets

For the GitHub Actions workflow to work, you need to add the following secrets to your repository:

1. `GITEA_DEPLOY_KEY`: The contents of the `.deploy-key` file
2. `GITEA_TOKEN`: The contents of the `.gitea-token` file

To add these secrets:
1. Go to your repository on GitHub
2. Click on "Settings"
3. Click on "Secrets and variables" > "Actions"
4. Click on "New repository secret"
5. Add each secret with the appropriate name and value

## Security Considerations

- **Never commit the private key or token to the repository**
- The `.deploy-key`, `.deploy-key.pub`, and `.gitea-token` files are already in `.gitignore`
- Rotate the deploy key and token periodically for better security
- Limit the permissions of the token to only what is necessary (packages:write)

## Troubleshooting

### Authentication Errors

If you encounter authentication errors when publishing:

1. Verify that your Gitea token has the correct permissions
2. Check that the token is correctly set in the `.gitea-token` file
3. Ensure the deploy key has been added to the repository with write access

### SSH Key Issues

If there are issues with the SSH key:

1. Verify that the key has been added to the repository
2. Check the permissions on the `.deploy-key` file (should be `600`)
3. Try regenerating the key with the setup script