g1-ts-common-packages/docs/DEPLOY_KEYS.md

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:

# 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:

{
  "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:

# 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