GitHub Secrets Configuration

This document explains how to configure the required GitHub secrets for automated package publishing.

Required Secrets

The automated release workflow requires the following secrets to be configured in the GitHub repository settings:

1. AUR_SSH_KEY

Purpose: Authenticate with AUR to publish packages

How to generate:

# Generate SSH key pair
ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/aur

# Add public key to AUR
# Go to https://aur.archlinux.org/account/
# Navigate to "My Account" → "SSH Public Key"
# Paste contents of ~/.ssh/aur.pub

# Copy private key for GitHub secret
cat ~/.ssh/aur

Add to GitHub:

1. Go to repository Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: AUR_SSH_KEY
4. Value: Paste the private key (contents of ~/.ssh/aur)

2. SNAPCRAFT_TOKEN

Purpose: Authenticate with Snap Store to publish snaps

How to generate:

# Login to Snapcraft (first time)
snapcraft login

# Export credentials
snapcraft export-login snapcraft-token.txt

# View the token
cat snapcraft-token.txt

Add to GitHub:

1. Go to repository Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: SNAPCRAFT_TOKEN
4. Value: Paste the contents of snapcraft-token.txt

Security note: Delete snapcraft-token.txt after adding to GitHub secrets.

3. FLATPAK_TOKEN

Purpose: Create PRs on Flathub repositories

How to generate:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it a descriptive name: "UTPM Flatpak Publishing"
4. Set expiration as desired (or "No expiration" for convenience)
5. Select scopes:
   • public_repo (for creating PRs)
6. Click "Generate token"
7. Copy the token immediately (you won't be able to see it again)

Add to GitHub:

1. Go to repository Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: FLATPAK_TOKEN
4. Value: Paste the GitHub token

Verification

After adding all secrets, trigger a test release:

# Create a test tag
git tag v0.0.0-test
git push --tags

# Watch the Actions tab
# https://github.com/typst-community/utpm/actions

Check that all publishing jobs complete successfully:

• ✅ publish-aur
• ✅ publish-homebrew
• ✅ publish-snap
• ✅ publish-flatpak

Troubleshooting

AUR Publishing Fails

Error: Permission denied (publickey)

Solution:

• Verify SSH key is added to AUR account
• Verify private key is correctly pasted in AUR_SSH_KEY secret
• Check that key doesn't have a passphrase (GitHub Actions can't handle passphrases)

Snap Publishing Fails

Error: Invalid credentials

Solution:

• Re-export credentials: snapcraft export-login snapcraft-token.txt
• Update SNAPCRAFT_TOKEN secret with new credentials
• Verify you have permissions to publish to the snap name

Flatpak PR Fails

Error: 403 Forbidden

Solution:

• Verify GitHub token has public_repo scope
• Check token hasn't expired
• Ensure token belongs to a user with push access to the fork

Security Best Practices

1. Rotate secrets regularly - Update tokens/keys every 6-12 months
2. Use minimal permissions - Only grant necessary scopes
3. Monitor Actions logs - Check for unauthorized access attempts
4. Never commit secrets - Always use GitHub Secrets, never hardcode
5. Delete local credentials - Remove exported files after adding to secrets

Revoking Access

If secrets are compromised:

1. AUR: Remove SSH key from https://aur.archlinux.org/account/
2. Snap Store: Revoke via snapcraft logout and regenerate
3. GitHub Token: Revoke at https://github.com/settings/tokens
4. Update secrets: Generate new credentials and update GitHub secrets

Repository Setup Checklist

For new maintainers setting up automation:

• Generate AUR SSH key and add to AUR account
• Export Snapcraft credentials
• Generate GitHub token for Flatpak
• Add all three secrets to GitHub repository
• Create homebrew-utpm repository under typst-community
• Fork Flathub app repository to typst-community
• Test with a pre-release tag
• Document any issues in this file

---

Last Updated: November 2025