{"version":"https:\/\/jsonfeed.org\/version\/1","title":"GitHub Actions on Just a Theory","description":"An ongoing list of Just a Theory posts about GitHub Actions","home_page_url":"https:\/\/justatheory.com\/tags\/github-actions\/","feed_url":"https:\/\/justatheory.com\/tags\/github-actions\/feed.json","icon":"https:\/\/justatheory.com\/icon-512x512.png","favicon":"https:\/\/justatheory.com\/icon-64x64.png","items":[{"id":"https:\/\/justatheory.com\/2025\/05\/release-on-pgxn\/","url":"https:\/\/justatheory.com\/2025\/05\/release-on-pgxn\/","title":"Auto-Release PostgreSQL Extensions on PGXN","summary":"Step-by-step instructions to publish PostgreSQL extensions and utilities on\nthe PostgreSQL Extension Network (PGXN).\n","date_published":"2025-05-20T15:49:30Z","authors":[{"name":"David E. Wheeler","url":"https:\/\/justatheory.com\/"}],"tags":["Postgres","PGXN","Extension","GitHub","GitHub Actions","Automation","CI\/CD"],"content_html":"
\n
\n

I last wrote about auto-releasing PostgreSQL extensions on PGXN back in\n2020<\/a>, but I thought it worthwhile, following my Postgres\nExtensions Day<\/a> talk last week, to return again to the basics. With the\ngoal to get as many extensions distributed on PGXN<\/a> as possible, this post\nprovides step-by-step instructions to help the author of any extension or\nPostgres utility to quickly and easily publish every release.<\/p>\n

TL;DR<\/h2>\n
    \n
  1. Create a PGXN Manager<\/a> account<\/li>\n
  2. Add a META.json<\/code><\/a> file to your project<\/li>\n
  3. Add a pgxn-tools<\/a> powered CI\/CD pipeline to publish on tag push<\/li>\n
  4. Fully-document<\/a> your extensions<\/li>\n<\/ol>\n

    Release your extensions on PGXN<\/h2>\n

    PGXN<\/a> aims to become the defacto source for all open-source PostgreSQL\nextensions and tools, in order to help users quickly find and learn how to use\nextensions to meet their needs. Currently, PGXN distributes source releases\nfor around 400 extensions (stats on the about page<\/a>), a fraction of the ca.\n1200 known extensions<\/a>. Anyone looking for an extension might exist to solve\nsome problem must rely on search engines to find potential solutions between\nPGXN, GitHub, GitLab, blogs, social media posts, and more. Without a single\ntrusted source for extensions, and with the proliferation of AI Slop<\/a> in\nsearch engine results, finding extensions aside from a few well-known\nsolutions proves a challenge.<\/p>\n

    By publishing releases and full documentation — all fully indexed by its\nsearch index — PGXN aims to be that trusted source. Extension authors\nprovide all the documentation, which PGXN formats for legibility and linking.\nSee, for example, the pgvector docs<\/a>.<\/p>\n

    If you want to make it easier for users to find your extensions, to read your\ndocumentation — not to mention provide sources for binary packaging systems\n— publish every release on PGXN.<\/p>\n

    Here’s how.<\/p>\n

    Create an Account<\/h3>\n

    Step one: create a PGXN Manager<\/a> account. The Email<\/em>, Nickname<\/em>, and Why<\/em>\nfields are required. The form asks “why” as a simple filter for bad actors.\nWrite a sentence describing what you’d like to release — ideally with a link\nto the source repository — and submit. We’ll get the account approved\nforthwith, which will send a confirmation email to your address. Follow the\nlink in the email and you’ll be good to go.<\/p>\n

    Anatomy of a Distribution<\/h3>\n

    A PostgreSQL extension source tree generally looks something like this (taken\nfrom the pair repository<\/a>):<\/p>\n

    pair\n\u251c\u2500\u2500 Changes\n\u251c\u2500\u2500 doc\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 pair.md\n\u251c\u2500\u2500 Makefile\n\u251c\u2500\u2500 META.json\n\u251c\u2500\u2500 pair.control\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 sql\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pair--unpackaged--0.1.2.sql\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 pair.sql\n\u2514\u2500\u2500 test\n    \u251c\u2500\u2500 expected\n    \u2502\u00a0\u00a0 \u2514\u2500\u2500 base.out\n    \u2514\u2500\u2500 sql\n        \u2514\u2500\u2500 base.sql\n<\/code><\/pre>
    Extension authors will recognize the standard PGXS<\/a> (or pgrx<\/a>) source\ndistribution files; only META.json<\/code> file needs explaining. The META.json<\/code>\nfile is, frankly, the only file that PGXN requires in a release. It contains\nthe metadata to describe the release, following the PGXN Meta Spec<\/a>.\nThis example contains only the required fields:<\/p>\n
    {<\/span>\n<\/span><\/span>  "name"<\/span>:<\/span> "pair"<\/span>,<\/span>\n<\/span><\/span>  "version"<\/span>:<\/span> "0.1.0"<\/span>,<\/span>\n<\/span><\/span>  "abstract"<\/span>:<\/span> "A key\/value pair data type"<\/span>,<\/span>\n<\/span><\/span>  "maintainer"<\/span>:<\/span> "David E. Wheeler <david@justatheory.com>"<\/span>,<\/span>\n<\/span><\/span>  "license"<\/span>:<\/span> "postgresql"<\/span>,<\/span>\n<\/span><\/span>  "provides"<\/span>:<\/span> {<\/span>\n<\/span><\/span>    "pair"<\/span>:<\/span> {<\/span>\n<\/span><\/span>      "file"<\/span>:<\/span> "sql\/pair.sql"<\/span>,<\/span>\n<\/span><\/span>      "version"<\/span>:<\/span> "0.1.0"<\/span>\n<\/span><\/span>    }<\/span>\n<\/span><\/span>  },<\/span>\n<\/span><\/span>  "meta-spec"<\/span>:<\/span> {<\/span>\n<\/span><\/span>    "version"<\/span>:<\/span> "1.0.0"<\/span>\n<\/span><\/span>  }<\/span>\n<\/span><\/span>}<\/span>\n<\/span><\/span><\/code><\/pre><\/div>
    Presumably these fields contain no surprises, but a couple of details:<\/p>\n