# Automate versions and releases with release-please

> Run release-please on Githome with the release-please action or its CLI: the workflow, the permissions and setting it needs, CI on release pull requests, and troubleshooting.

Source: https://git.pkgforge.dev/docs/guides/release-please

> **Note:** The forge CI of git.pkgforge.dev is dormant, so the workflow below starts no run there now. The CLI route (see below) runs from your own terminal and does not need the forge CI.

[release-please](https://github.com/googleapis/release-please) reads your Conventional Commits, keeps a release pull request open with the next version and changelog, and creates the tag and release when you merge it. It works on Githome as it does on GitHub: the `googleapis/release-please-action@v4` action runs unchanged, and the `release-please` CLI works with Githome's API URLs. Githome answers the GraphQL queries release-please sends (commit history with each commit's pull request, merged pull requests and releases) and the REST calls it makes (files, git data, pull requests, labels, tags and releases).

## Steps

1. **Keep your release-please files.** `release-please-config.json` and `.release-please-manifest.json` (or the action's `release-type` input) work as they are. An imported repository already has them.
2. **Let workflows open pull requests.** Open the repository's **Settings → Actions** tab, check **Allow GitHub Actions to create and approve pull requests** under **Workflow permissions**, and click **Save**. This needs the admin role. It's off by default, as on GitHub, and without it the action fails with `GitHub Actions is not permitted to create pull requests.` See [GITHUB_TOKEN permissions](https://git.pkgforge.dev/docs/actions/workflow-permissions#creating-and-approving-pull-requests).
3. **Add the workflow.** The same file as on GitHub:

   ```yaml
   # .github/workflows/release-please.yml
   on:
     push:
       branches: [main]

   permissions:
     contents: write       # tags and releases
     pull-requests: write  # the release pull request
     issues: write         # its labels

   jobs:
     release-please:
       runs-on: ubuntu-latest
       outputs:
         release_created: ${{ steps.release.outputs.release_created }}
         tag_name: ${{ steps.release.outputs.tag_name }}
       steps:
         - uses: googleapis/release-please-action@v4
           id: release
           with:
             release-type: node   # or leave it out and keep release-please-config.json
   ```

   The action's `github-api-url`, `github-graphql-url` and `changelog-host` inputs default to `${{ github.api_url }}`, `${{ github.graphql_url }}` and `${{ github.server_url }}`, which point at Githome, so you don't set them. Changelog links point at your repository on Githome.
4. **Build and ship from the release.** Later jobs read the outputs, as on GitHub, for example to build and upload a mobile app only when a release was created:

   ```yaml
     ship:
       needs: release-please
       if: ${{ needs.release-please.outputs.release_created == 'true' }}
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: ./scripts/ship.sh "${{ needs.release-please.outputs.tag_name }}"
   ```

5. **Merge the release pull request** when you want to release. Squash, merge commit and rebase merges all work. The next run of the workflow tags the merge, creates the release and relabels the pull request `autorelease: tagged`.

## CI on the release pull request

As on GitHub, what a job's `GITHUB_TOKEN` does starts no new workflow runs, so a release pull request opened with it gets no `pull_request` runs. If your branch protection requires checks, give the action a token of its own: a [personal or agent token](https://git.pkgforge.dev/docs/accounts/tokens) with the `write` scope, stored as a secret.

```yaml
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
```

Pull requests and pushes made with that token start workflows like anyone else's. If it's an [agent's](https://git.pkgforge.dev/docs/guides/ai-agent-with-guardrails) token, the agent rules apply: it opens and updates the release pull request, and a person merges it.

## The CLI

Run release-please from a terminal or another CI system with Githome's REST and GraphQL URLs. `--graphql-url` is the address without `/graphql` (release-please adds it):

```sh
export GITHOME_TOKEN=ghome_...   # a token with the write scope
npx release-please release-pr --repo-url acme/app --token "$GITHOME_TOKEN" \
  --api-url https://git.pkgforge.dev/api/v3 --graphql-url https://git.pkgforge.dev/api
npx release-please github-release --repo-url acme/app --token "$GITHOME_TOKEN" \
  --api-url https://git.pkgforge.dev/api/v3 --graphql-url https://git.pkgforge.dev/api
```

`--target-branch` picks another branch than the default one. For changelog links that point at Githome when you use the CLI, add `"changelog-host": "https://git.pkgforge.dev"` to `release-please-config.json`; the action sets it for you.

## Troubleshooting

| Message | Fix |
| --- | --- |
| `GitHub Actions is not permitted to create pull requests.` | Check **Allow GitHub Actions to create and approve pull requests** (step 2), or use a token of its own. |
| `Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: ...)` | Add the `permissions:` from step 3 to the workflow or job. |
| `release-please failed: Error updating ref heads/release-please--branches--...` (the API answered ``refusing to allow a GitHub App to create or update workflow `...` without `workflows` permission``) | A workflow file changed on the base branch while the release pull request was open. Rebuilding the release branch on the new base would change workflow files on it, which a job's `GITHUB_TOKEN` may never do on Githome. Merge or close the release pull request and delete its branch (the next run opens a fresh one), or give the action a [token of its own](#ci-on-the-release-pull-request). |
| `Could not find commits for branch <name> - it likely does not exist.` | The branch in `target-branch` (or the default branch) doesn't exist, or the token can't read the repository. |
| Changelog links go to github.com | Set `changelog-host` (CLI), or check that the action's `changelog-host` input isn't set to GitHub. |
| `No commits for path: ., skipping` | Nothing since the last release follows Conventional Commits (`feat:`, `fix:`, `feat!:` and so on), so there's nothing to release. |

## Related

- [Releases](https://git.pkgforge.dev/docs/collaboration/releases): tags, drafts, notes and assets.
- [GraphQL API](https://git.pkgforge.dev/docs/reference/graphql-api): the queries Githome answers.
- [Move your GitHub Actions workflows to Githome](https://git.pkgforge.dev/docs/guides/move-github-actions-workflows).