[{"data":1,"prerenderedAt":757},["ShallowReactive",2],{"\u002Fdocs\u002Freleases":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"body":10,"_type":751,"_id":752,"_source":753,"_file":754,"_stem":755,"_extension":756},"\u002Fdocs\u002Freleases","docs",false,"","Cutting releases","A deploy tells i3deploy that something shipped. A release tells it what changed — the\nchangelog your team and your users actually read. i3deploy models that at two levels:",{"type":11,"children":12,"toc":743},"root",[13,21,42,103,124,129,136,143,319,345,351,521,594,642,648,662,671,699,705,737],{"type":14,"tag":15,"props":16,"children":18},"element","h1",{"id":17},"cutting-releases",[19],{"type":20,"value":8},"text",{"type":14,"tag":22,"props":23,"children":24},"p",{},[25,27,33,35,40],{"type":20,"value":26},"A deploy tells i3deploy ",{"type":14,"tag":28,"props":29,"children":30},"em",{},[31],{"type":20,"value":32},"that",{"type":20,"value":34}," something shipped. A release tells it ",{"type":14,"tag":28,"props":36,"children":37},{},[38],{"type":20,"value":39},"what changed",{"type":20,"value":41}," — the\nchangelog your team and your users actually read. i3deploy models that at two levels:",{"type":14,"tag":43,"props":44,"children":45},"ul",{},[46,77],{"type":14,"tag":47,"props":48,"children":49},"li",{},[50,52,58,60,67,69,75],{"type":20,"value":51},"A ",{"type":14,"tag":53,"props":54,"children":55},"strong",{},[56],{"type":20,"value":57},"ServiceRelease",{"type":20,"value":59}," is one service's version: its commit range, and a changelog in two\nflavors — ",{"type":14,"tag":61,"props":62,"children":64},"code",{"className":63},[],[65],{"type":20,"value":66},"changelog_markdown",{"type":20,"value":68}," (technical notes) and ",{"type":14,"tag":61,"props":70,"children":72},{"className":71},[],[73],{"type":20,"value":74},"markdown_users",{"type":20,"value":76}," (user-facing notes).",{"type":14,"tag":47,"props":78,"children":79},{},[80,81,86,88,93,95,101],{"type":20,"value":51},{"type":14,"tag":53,"props":82,"children":83},{},[84],{"type":20,"value":85},"ProjectRelease",{"type":20,"value":87}," bundles one or more service releases under a single project-facing\nversion — the thing you'd point an end user at (\"what's new in 2.4\"). It also carries two\nchangelogs, ",{"type":14,"tag":61,"props":89,"children":91},{"className":90},[],[92],{"type":20,"value":74},{"type":20,"value":94}," and ",{"type":14,"tag":61,"props":96,"children":98},{"className":97},[],[99],{"type":20,"value":100},"markdown_techies",{"type":20,"value":102},", so the same release can read differently\nfor end users versus engineers.",{"type":14,"tag":22,"props":104,"children":105},{},[106,108,114,116,122],{"type":20,"value":107},"Both are tagged ",{"type":14,"tag":61,"props":109,"children":111},{"className":110},[],[112],{"type":20,"value":113},"authored_by: human",{"type":20,"value":115}," or ",{"type":14,"tag":61,"props":117,"children":119},{"className":118},[],[120],{"type":20,"value":121},"authored_by: ai",{"type":20,"value":123},", so it's always visible whether a\nchangelog was written by a person or drafted by Claude.",{"type":14,"tag":22,"props":125,"children":126},{},[127],{"type":20,"value":128},"Releases can be created two ways: directly against the API, or by asking Claude through the MCP\nconnector.",{"type":14,"tag":130,"props":131,"children":133},"h2",{"id":132},"via-the-api",[134],{"type":20,"value":135},"Via the API",{"type":14,"tag":137,"props":138,"children":140},"h3",{"id":139},"_1-create-a-service-release",[141],{"type":20,"value":142},"1. Create a service release",{"type":14,"tag":144,"props":145,"children":149},"pre",{"className":146,"code":147,"language":148,"meta":7,"style":7},"language-bash shiki shiki-themes github-dark","curl -X POST https:\u002F\u002Fbackend.i3deploy.com\u002Fv1\u002Fservice-releases \\\n  -H \"Authorization: Bearer $I3DEPLOY_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"service\": \"web\",\n    \"version\": \"1.4.2\",\n    \"commit_sha\": \"abc123\",\n    \"commit_range\": \"v1.4.1..v1.4.2\",\n    \"changelog_markdown\": \"- web: fixed checkout redirect loop\",\n    \"markdown_users\": \"- Fixed a bug where checkout could redirect in a loop\",\n    \"short_summary\": \"Fix checkout redirect loop\"\n  }'\n","bash",[150],{"type":14,"tag":61,"props":151,"children":152},{"__ignoreMap":7},[153,187,216,233,247,256,265,274,283,292,301,310],{"type":14,"tag":154,"props":155,"children":158},"span",{"class":156,"line":157},"line",1,[159,165,171,177,182],{"type":14,"tag":154,"props":160,"children":162},{"style":161},"--shiki-default:#B392F0",[163],{"type":20,"value":164},"curl",{"type":14,"tag":154,"props":166,"children":168},{"style":167},"--shiki-default:#79B8FF",[169],{"type":20,"value":170}," -X",{"type":14,"tag":154,"props":172,"children":174},{"style":173},"--shiki-default:#9ECBFF",[175],{"type":20,"value":176}," POST",{"type":14,"tag":154,"props":178,"children":179},{"style":173},[180],{"type":20,"value":181}," https:\u002F\u002Fbackend.i3deploy.com\u002Fv1\u002Fservice-releases",{"type":14,"tag":154,"props":183,"children":184},{"style":167},[185],{"type":20,"value":186}," \\\n",{"type":14,"tag":154,"props":188,"children":190},{"class":156,"line":189},2,[191,196,201,207,212],{"type":14,"tag":154,"props":192,"children":193},{"style":167},[194],{"type":20,"value":195},"  -H",{"type":14,"tag":154,"props":197,"children":198},{"style":173},[199],{"type":20,"value":200}," \"Authorization: Bearer ",{"type":14,"tag":154,"props":202,"children":204},{"style":203},"--shiki-default:#E1E4E8",[205],{"type":20,"value":206},"$I3DEPLOY_API_KEY",{"type":14,"tag":154,"props":208,"children":209},{"style":173},[210],{"type":20,"value":211},"\"",{"type":14,"tag":154,"props":213,"children":214},{"style":167},[215],{"type":20,"value":186},{"type":14,"tag":154,"props":217,"children":219},{"class":156,"line":218},3,[220,224,229],{"type":14,"tag":154,"props":221,"children":222},{"style":167},[223],{"type":20,"value":195},{"type":14,"tag":154,"props":225,"children":226},{"style":173},[227],{"type":20,"value":228}," \"Content-Type: application\u002Fjson\"",{"type":14,"tag":154,"props":230,"children":231},{"style":167},[232],{"type":20,"value":186},{"type":14,"tag":154,"props":234,"children":236},{"class":156,"line":235},4,[237,242],{"type":14,"tag":154,"props":238,"children":239},{"style":167},[240],{"type":20,"value":241},"  -d",{"type":14,"tag":154,"props":243,"children":244},{"style":173},[245],{"type":20,"value":246}," '{\n",{"type":14,"tag":154,"props":248,"children":250},{"class":156,"line":249},5,[251],{"type":14,"tag":154,"props":252,"children":253},{"style":173},[254],{"type":20,"value":255},"    \"service\": \"web\",\n",{"type":14,"tag":154,"props":257,"children":259},{"class":156,"line":258},6,[260],{"type":14,"tag":154,"props":261,"children":262},{"style":173},[263],{"type":20,"value":264},"    \"version\": \"1.4.2\",\n",{"type":14,"tag":154,"props":266,"children":268},{"class":156,"line":267},7,[269],{"type":14,"tag":154,"props":270,"children":271},{"style":173},[272],{"type":20,"value":273},"    \"commit_sha\": \"abc123\",\n",{"type":14,"tag":154,"props":275,"children":277},{"class":156,"line":276},8,[278],{"type":14,"tag":154,"props":279,"children":280},{"style":173},[281],{"type":20,"value":282},"    \"commit_range\": \"v1.4.1..v1.4.2\",\n",{"type":14,"tag":154,"props":284,"children":286},{"class":156,"line":285},9,[287],{"type":14,"tag":154,"props":288,"children":289},{"style":173},[290],{"type":20,"value":291},"    \"changelog_markdown\": \"- web: fixed checkout redirect loop\",\n",{"type":14,"tag":154,"props":293,"children":295},{"class":156,"line":294},10,[296],{"type":14,"tag":154,"props":297,"children":298},{"style":173},[299],{"type":20,"value":300},"    \"markdown_users\": \"- Fixed a bug where checkout could redirect in a loop\",\n",{"type":14,"tag":154,"props":302,"children":304},{"class":156,"line":303},11,[305],{"type":14,"tag":154,"props":306,"children":307},{"style":173},[308],{"type":20,"value":309},"    \"short_summary\": \"Fix checkout redirect loop\"\n",{"type":14,"tag":154,"props":311,"children":313},{"class":156,"line":312},12,[314],{"type":14,"tag":154,"props":315,"children":316},{"style":173},[317],{"type":20,"value":318},"  }'\n",{"type":14,"tag":22,"props":320,"children":321},{},[322,328,330,336,338,343],{"type":14,"tag":61,"props":323,"children":325},{"className":324},[],[326],{"type":20,"value":327},"service",{"type":20,"value":329}," is the service's slug, scoped to your organization. ",{"type":14,"tag":61,"props":331,"children":333},{"className":332},[],[334],{"type":20,"value":335},"version",{"type":20,"value":337}," + ",{"type":14,"tag":61,"props":339,"children":341},{"className":340},[],[342],{"type":20,"value":327},{"type":20,"value":344}," must be\nunique together — you can't create two releases for the same service\u002Fversion pair.",{"type":14,"tag":137,"props":346,"children":348},{"id":347},"_2-bundle-it-into-a-project-release",[349],{"type":20,"value":350},"2. Bundle it into a project release",{"type":14,"tag":144,"props":352,"children":354},{"className":146,"code":353,"language":148,"meta":7,"style":7},"curl -X POST https:\u002F\u002Fbackend.i3deploy.com\u002Fv1\u002Fproject-releases \\\n  -H \"Authorization: Bearer $I3DEPLOY_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"project\": \"marketing-site\",\n    \"title\": \"2.4\",\n    \"short\": \"Checkout fixes and a faster homepage\",\n    \"version_numeric\": \"2.4.0\",\n    \"markdown_users\": \"## 2.4\\n\\n- Fixed a checkout bug that could loop the redirect\\n- Faster homepage load\",\n    \"markdown_techies\": \"## 2.4\\n\\n- web: fixed checkout redirect loop (abc123)\\n- api: added response caching for \u002Fhomepage\",\n    \"published\": true,\n    \"service_releases\": [\n      {\"service\": \"web\", \"version\": \"1.4.2\"}\n    ]\n  }'\n",[355],{"type":14,"tag":61,"props":356,"children":357},{"__ignoreMap":7},[358,382,405,420,431,439,447,455,463,471,479,487,495,504,513],{"type":14,"tag":154,"props":359,"children":360},{"class":156,"line":157},[361,365,369,373,378],{"type":14,"tag":154,"props":362,"children":363},{"style":161},[364],{"type":20,"value":164},{"type":14,"tag":154,"props":366,"children":367},{"style":167},[368],{"type":20,"value":170},{"type":14,"tag":154,"props":370,"children":371},{"style":173},[372],{"type":20,"value":176},{"type":14,"tag":154,"props":374,"children":375},{"style":173},[376],{"type":20,"value":377}," https:\u002F\u002Fbackend.i3deploy.com\u002Fv1\u002Fproject-releases",{"type":14,"tag":154,"props":379,"children":380},{"style":167},[381],{"type":20,"value":186},{"type":14,"tag":154,"props":383,"children":384},{"class":156,"line":189},[385,389,393,397,401],{"type":14,"tag":154,"props":386,"children":387},{"style":167},[388],{"type":20,"value":195},{"type":14,"tag":154,"props":390,"children":391},{"style":173},[392],{"type":20,"value":200},{"type":14,"tag":154,"props":394,"children":395},{"style":203},[396],{"type":20,"value":206},{"type":14,"tag":154,"props":398,"children":399},{"style":173},[400],{"type":20,"value":211},{"type":14,"tag":154,"props":402,"children":403},{"style":167},[404],{"type":20,"value":186},{"type":14,"tag":154,"props":406,"children":407},{"class":156,"line":218},[408,412,416],{"type":14,"tag":154,"props":409,"children":410},{"style":167},[411],{"type":20,"value":195},{"type":14,"tag":154,"props":413,"children":414},{"style":173},[415],{"type":20,"value":228},{"type":14,"tag":154,"props":417,"children":418},{"style":167},[419],{"type":20,"value":186},{"type":14,"tag":154,"props":421,"children":422},{"class":156,"line":235},[423,427],{"type":14,"tag":154,"props":424,"children":425},{"style":167},[426],{"type":20,"value":241},{"type":14,"tag":154,"props":428,"children":429},{"style":173},[430],{"type":20,"value":246},{"type":14,"tag":154,"props":432,"children":433},{"class":156,"line":249},[434],{"type":14,"tag":154,"props":435,"children":436},{"style":173},[437],{"type":20,"value":438},"    \"project\": \"marketing-site\",\n",{"type":14,"tag":154,"props":440,"children":441},{"class":156,"line":258},[442],{"type":14,"tag":154,"props":443,"children":444},{"style":173},[445],{"type":20,"value":446},"    \"title\": \"2.4\",\n",{"type":14,"tag":154,"props":448,"children":449},{"class":156,"line":267},[450],{"type":14,"tag":154,"props":451,"children":452},{"style":173},[453],{"type":20,"value":454},"    \"short\": \"Checkout fixes and a faster homepage\",\n",{"type":14,"tag":154,"props":456,"children":457},{"class":156,"line":276},[458],{"type":14,"tag":154,"props":459,"children":460},{"style":173},[461],{"type":20,"value":462},"    \"version_numeric\": \"2.4.0\",\n",{"type":14,"tag":154,"props":464,"children":465},{"class":156,"line":285},[466],{"type":14,"tag":154,"props":467,"children":468},{"style":173},[469],{"type":20,"value":470},"    \"markdown_users\": \"## 2.4\\n\\n- Fixed a checkout bug that could loop the redirect\\n- Faster homepage load\",\n",{"type":14,"tag":154,"props":472,"children":473},{"class":156,"line":294},[474],{"type":14,"tag":154,"props":475,"children":476},{"style":173},[477],{"type":20,"value":478},"    \"markdown_techies\": \"## 2.4\\n\\n- web: fixed checkout redirect loop (abc123)\\n- api: added response caching for \u002Fhomepage\",\n",{"type":14,"tag":154,"props":480,"children":481},{"class":156,"line":303},[482],{"type":14,"tag":154,"props":483,"children":484},{"style":173},[485],{"type":20,"value":486},"    \"published\": true,\n",{"type":14,"tag":154,"props":488,"children":489},{"class":156,"line":312},[490],{"type":14,"tag":154,"props":491,"children":492},{"style":173},[493],{"type":20,"value":494},"    \"service_releases\": [\n",{"type":14,"tag":154,"props":496,"children":498},{"class":156,"line":497},13,[499],{"type":14,"tag":154,"props":500,"children":501},{"style":173},[502],{"type":20,"value":503},"      {\"service\": \"web\", \"version\": \"1.4.2\"}\n",{"type":14,"tag":154,"props":505,"children":507},{"class":156,"line":506},14,[508],{"type":14,"tag":154,"props":509,"children":510},{"style":173},[511],{"type":20,"value":512},"    ]\n",{"type":14,"tag":154,"props":514,"children":516},{"class":156,"line":515},15,[517],{"type":14,"tag":154,"props":518,"children":519},{"style":173},[520],{"type":20,"value":318},{"type":14,"tag":22,"props":522,"children":523},{},[524,530,532,538,540,546,548,554,556,562,564,569,571,576,578,584,586,592],{"type":14,"tag":61,"props":525,"children":527},{"className":526},[],[528],{"type":20,"value":529},"project",{"type":20,"value":531}," is the project's slug. ",{"type":14,"tag":61,"props":533,"children":535},{"className":534},[],[536],{"type":20,"value":537},"version_numeric",{"type":20,"value":539}," is the release's version string (semver-ish —\ni3deploy parses it into major\u002Fminor\u002Fpatch for ordering); ",{"type":14,"tag":61,"props":541,"children":543},{"className":542},[],[544],{"type":20,"value":545},"title",{"type":20,"value":547}," is a separate, freeform headline\nthat doesn't have to be just the version number. ",{"type":14,"tag":61,"props":549,"children":551},{"className":550},[],[552],{"type":20,"value":553},"service_releases",{"type":20,"value":555}," takes ",{"type":14,"tag":61,"props":557,"children":559},{"className":558},[],[560],{"type":20,"value":561},"{service, version}",{"type":20,"value":563},"\npairs referencing ",{"type":14,"tag":53,"props":565,"children":566},{},[567],{"type":20,"value":568},"already-created",{"type":20,"value":570}," service releases — create those first, then bundle them.\nEvery referenced service must belong to the same organization as ",{"type":14,"tag":61,"props":572,"children":574},{"className":573},[],[575],{"type":20,"value":529},{"type":20,"value":577},", or the request is\nrejected. Set ",{"type":14,"tag":61,"props":579,"children":581},{"className":580},[],[582],{"type":20,"value":583},"published: true",{"type":20,"value":585}," (the default) when the release should show up in the public\nmanifest right away; set it ",{"type":14,"tag":61,"props":587,"children":589},{"className":588},[],[590],{"type":20,"value":591},"false",{"type":20,"value":593}," to stage the changelog before flipping it live.",{"type":14,"tag":22,"props":595,"children":596},{},[597,599,604,606,611,613,618,619,625,627,633,635,640],{"type":20,"value":598},"On read, ",{"type":14,"tag":61,"props":600,"children":602},{"className":601},[],[603],{"type":20,"value":553},{"type":20,"value":605}," comes back expanded (",{"type":14,"tag":61,"props":607,"children":609},{"className":608},[],[610],{"type":20,"value":327},{"type":20,"value":612},", ",{"type":14,"tag":61,"props":614,"children":616},{"className":615},[],[617],{"type":20,"value":335},{"type":20,"value":612},{"type":14,"tag":61,"props":620,"children":622},{"className":621},[],[623],{"type":20,"value":624},"commit_sha",{"type":20,"value":626},",\n",{"type":14,"tag":61,"props":628,"children":630},{"className":629},[],[631],{"type":20,"value":632},"authored_by",{"type":20,"value":634},") instead of the write-only ",{"type":14,"tag":61,"props":636,"children":638},{"className":637},[],[639],{"type":20,"value":561},{"type":20,"value":641}," pairs you sent.",{"type":14,"tag":130,"props":643,"children":645},{"id":644},"via-mcp-claude",[646],{"type":20,"value":647},"Via MCP \u002F Claude",{"type":14,"tag":22,"props":649,"children":650},{},[651,653,660],{"type":20,"value":652},"Once the ",{"type":14,"tag":654,"props":655,"children":657},"a",{"href":656},"\u002Fdocs\u002Fmcp-connector",[658],{"type":20,"value":659},"MCP connector",{"type":20,"value":661}," is wired up, you don't need to touch curl at all —\njust ask:",{"type":14,"tag":663,"props":664,"children":665},"blockquote",{},[666],{"type":14,"tag":22,"props":667,"children":668},{},[669],{"type":20,"value":670},"\"Cut release 2.4 for marketing-site: bundle web 1.4.2, and write a changelog — fixed the\ncheckout redirect loop, faster homepage.\"",{"type":14,"tag":22,"props":672,"children":673},{},[674,676,682,684,690,692,697],{"type":20,"value":675},"Claude reads the deploys and commits it has visibility into, drafts both a user-facing and a\ntechnical changelog, and calls the same ",{"type":14,"tag":61,"props":677,"children":679},{"className":678},[],[680],{"type":20,"value":681},"service-releases",{"type":20,"value":683}," \u002F ",{"type":14,"tag":61,"props":685,"children":687},{"className":686},[],[688],{"type":20,"value":689},"project-releases",{"type":20,"value":691}," write tools under\nthe hood — so the result is identical to calling the API directly, minus writing curl and JSON by\nhand. Releases authored this way are marked ",{"type":14,"tag":61,"props":693,"children":695},{"className":694},[],[696],{"type":20,"value":121},{"type":20,"value":698},".",{"type":14,"tag":130,"props":700,"children":702},{"id":701},"next",[703],{"type":20,"value":704},"Next",{"type":14,"tag":43,"props":706,"children":707},{},[708,719],{"type":14,"tag":47,"props":709,"children":710},{},[711,717],{"type":14,"tag":654,"props":712,"children":714},{"href":713},"\u002Fdocs\u002Fapi",[715],{"type":20,"value":716},"API guide",{"type":20,"value":718}," — full endpoint reference and auth details.",{"type":14,"tag":47,"props":720,"children":721},{},[722,728,730,735],{"type":14,"tag":654,"props":723,"children":725},{"href":724},"\u002Fdocs\u002Fmanifest",[726],{"type":20,"value":727},"The public manifest",{"type":20,"value":729}," — how a published ",{"type":14,"tag":61,"props":731,"children":733},{"className":732},[],[734],{"type":20,"value":85},{"type":20,"value":736}," shows up in the JSON\nfeed that clients read.",{"type":14,"tag":738,"props":739,"children":740},"style",{},[741],{"type":20,"value":742},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":7,"searchDepth":189,"depth":189,"links":744},[745,749,750],{"id":132,"depth":189,"text":135,"children":746},[747,748],{"id":139,"depth":218,"text":142},{"id":347,"depth":218,"text":350},{"id":644,"depth":189,"text":647},{"id":701,"depth":189,"text":704},"markdown","content:docs:releases.md","content","docs\u002Freleases.md","docs\u002Freleases","md",1784716250634]