A GitHub Action that turns boring PR numbers into memorable codenames like "tokyo" or "elephant". Because saying "Can you check the london branch?" sounds way better than "Can you check PR #1247?"
Built on top of the codenames library, this action generates deterministic, human-readable names from numbers. Same number in = same name out, every time.
You know that moment when someone mentions "PR #1247" in Slack and you have zero idea which one they're talking about? This fixes that. Instead of forgetting numbers, you'll remember names like "tokyo" or "elephant" - because human brains are weird like that.
name: Generate PR Codename
on:
pull_request:
types: [opened, synchronize]
jobs:
codename:
runs-on: ubuntu-latest
steps:
- uses: kriasoft/pr-codename@v1
id: codename
- name: Comment with codename
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `🏷️ **Codename:** ${{ steps.codename.outputs.codename }}`
})Now your PRs get friendly names automatically. Your teammates will thank you (probably).
| Input | Description | Required | Default |
|---|---|---|---|
number |
Number to convert (auto-detects PR number) | No | Auto-detected |
theme |
Word theme to use (see available themes below) | No | cities-20 |
template |
Output template with {codename} and {number} placeholders |
No | - |
token |
GitHub token for API access (for push events) | No | GITHUB_TOKEN env var |
| Output | Description | Example |
|---|---|---|
codename |
The generated codename | tokyo |
number |
The input number used | 1247 |
formatted |
Template result (when template is provided) | https://tokyo.preview.com |
Pick your flavor of memorable names:
- Animals:
animals-10,animals-20,animals-30,animals-50,animals-100 - Cities:
cities-10,cities-20,cities-30,cities-50,cities-100 - Colors:
colors-10,colors-20,colors-30,colors-50,colors-100 - Food:
food-10,food-20,food-30,food-50,food-100 - Nature:
nature-10,nature-20,nature-30,nature-50,nature-100 - Plus:
adjectives,clothing,countries,elements,emotions,gems,snacks
The number indicates how many words are in that theme (more words = less chance of repeats, but potentially less memorable names).
Stop squinting at URLs with random hashes:
- uses: kriasoft/pr-codename@v1
id: codename
with:
theme: cities-30
template: "https://{codename}.preview.myapp.com"
- name: Deploy preview
run: |
echo "🚀 Deploying to ${{ steps.codename.outputs.formatted }}"
# Deploy your app hereBecause app-1247 is forgettable but app-elephant sticks:
- uses: kriasoft/pr-codename@v1
id: codename
with:
theme: animals-50
- name: Build and tag container
run: |
docker build -t myapp:${{ steps.codename.outputs.codename }} .
echo "📦 Built container: myapp:${{ steps.codename.outputs.codename }}"Make your notifications actually readable:
- uses: kriasoft/pr-codename@v1
id: codename
- name: Notify team
run: |
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"🎉 The **${{ steps.codename.outputs.codename }}** branch is ready for review!\nPR: ${{ github.event.pull_request.html_url }}"}' \
${{ secrets.SLACK_WEBHOOK_URL }}Great for long-running feature work:
- uses: kriasoft/pr-codename@v1
id: codename
with:
number: ${{ github.event.issue.number }}
theme: gems-20
- name: Update issue with codename
uses: actions/github-script@v7
with:
script: |
const { data: issue } = await github.rest.issues.get({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number
});
if (!issue.body.includes('Codename:')) {
await github.rest.issues.update({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: issue.body + `\n\n**Codename:** ${{ steps.codename.outputs.codename }}`
});
}Not just for PRs - works with any number:
- uses: kriasoft/pr-codename@v1
with:
number: ${{ github.run_number }}
theme: nature-100
id: build-name
- run: echo "Build codename: ${{ steps.build-name.outputs.codename }}"- name: Generate environment codenames
run: |
# Different themes for different purposes
PREVIEW=$(echo '${{ steps.codename-cities.outputs.codename }}')
STAGING=$(echo '${{ steps.codename-animals.outputs.codename }}')
echo "Preview: https://$PREVIEW.preview.com"
echo "Staging: https://$STAGING.staging.com"The magic happens in the codenames library. It uses a deterministic hash function that:
- Takes your number (like PR #1247)
- Runs it through a consistent algorithm
- Maps it to a word from the chosen theme
- Always gives you the same result for the same input
No randomness, no database, no external calls. Just pure, predictable naming.
For push events and other non-PR contexts, the action needs GitHub API access to find the associated PR. Add these permissions to your workflow:
jobs:
codename:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read # Required for API fallback
steps:
- uses: kriasoft/pr-codename@v1
with:
token: ${{ secrets.GITHUB_TOKEN }} # Explicit tokenOr use the environment variable approach:
- uses: kriasoft/pr-codename@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Environment variableThe action will gracefully handle missing tokens by falling back to manual number input.
Q: Why am I getting "Could not determine number"?
A: The action tries to auto-detect PR numbers, but if you're not in a PR context, pass the number input manually or ensure proper GitHub token permissions.
Q: Can I use custom word lists?
A: Not directly in this action, but you can fork the codenames library and add your own themes.
Q: Are the names actually unique?
A: Within a theme's word count, yes. But with animals-10, you'll get repeats after 10 different numbers. Use larger themes for bigger projects.
Found a bug? Want a feature? The code is pretty straightforward:
index.ts- Main action logicaction.yml- GitHub Action metadata- Built on codenames
PRs welcome! (And yes, they'll get codenames too.)
MIT - Use it however you want. Build cool things.
Made with ☕ by Konstantin Tarkus and contributors.