PR Codename
ActionsTags
(2)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.
PR Codename is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
About
Tags
(2)PR Codename is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.