128 lines
3.8 KiB
Markdown
128 lines
3.8 KiB
Markdown
# 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
|