GitHub Short URLs - Shorten Long Issue, PR, and Blob URLs for Developer Workflows

GitHub URLs concatenate elements such as the owner name, repository name, branch name, and file path. For example, a permalink pointing to a specific line in a specific file looks like this:

`github.com/organization/repository-name/blob/a1b2c3d4e5f6/src/components/authentication/LoginForm.tsx#L42-L58`

Links to Issue and Pull Request comments also include fragments like `#issuecomment-1234567890`, making them even longer. Code review diff links can exceed 200 characters when file paths and hashes are combined.

Pasting these long URLs into Slack threads or emails lets the URL take up much of the message, making it harder to read.

GitHub once provided an official short URL service called `git.io`. However, new URL creation was stopped in 2022, and existing short URLs were moved to a read-only service and kept. This discontinuation eliminated the official means of shortening GitHub URLs.

Alternative options include:

• Using a short URL service on your own domain
• Operating short URLs with a custom domain
• Creating redirect pages in combination with GitHub Pages

In OSS projects, there is also the practice of using a project-specific subdomain (e.g., `go.project-name.dev/issue-123`) for short URLs.

A GitHub repository's README is the document that serves as the face of the project. Managing links in the README with short URLs offers several benefits.

Simplifying Badge URLs

CI status badges, coverage badges, and license badges are sometimes displayed at the top of a README, but the image URLs and link URLs for each badge are long, making the Markdown source code hard to read. Using short URLs makes badge Markdown concise and README editing easier.

Pathways to Documentation Sites

Some OSS projects maintain documentation sites separate from their GitHub repositories. When linking from the README to various pages on the documentation site, short URLs provide flexibility for destination changes. Even if the documentation site's URL structure changes, you only need to update the short URL redirect destination, with no README modifications required.

One practice is to send Slack or Teams notifications when CI/CD pipelines fail. Using short URLs for the links in these notification messages improves readability.

Implementation Pattern

In a GitHub Actions workflow, incorporate short URL generation into the step that sends Slack notifications on build failure. Specifically, send the failed workflow run URL to the short URL API and include the returned short URL in the Slack message.

The advantage of this approach is not only that notification messages become compact, but also that click counts offer clues about whether the logs were opened; if the notification review rate is low, this serves as a basis for improving notification recipients or message content.

Application to Deploy Notifications

Short URLs can also be used in deploy completion notifications. By organizing multiple URLs in a notification message - the deployed environment URL, the PR link for changes, and the rollback procedure documentation link - with short URLs, the necessary information becomes easier to find even in emergencies.

Embedding Short URLs in Issue Templates

Bug report and feature request Issue templates sometimes include links to contribution guides and codes of conduct. By using short URLs for these links, template modifications become unnecessary when guideline URLs change.

Use in Release Notes

Release notes may contain links to related Issues and PRs. Using short URLs makes release notes cleaner and makes it easier for users to follow the details of changes they are interested in.

When operating short URLs within a development team, establishing the following rules ensures smooth operations:

• Unify slug naming conventions (e.g., `repo-issue-123`, `repo-pr-456`)
• Set expiration dates for temporary links (review requests, etc.)
• Create permanent links (documentation, guidelines, etc.) without expiration
• Manage the short URL directory in Notion or a Wiki so the entire team has access

Documenting these rules in `CONTRIBUTING.md` can help new contributors learn the workflow. Short URLs are a small tool, but there are situations where they can reduce effort in the development workflow.