AGit Workflow Usage

Forgejo ships with custom support for AGit-Flow. Similarly to Gerrit’s workflow, this workflow provides a way of creating pull requests without having to create forks or feature branches (which require write permissions on the base repository).

Changing git default push method

For the AGit-flow the default push method of git (simple) is unsuitable and should be changed to upstream (the target branch is usually different from the local branch):

# Only needed once per repo (add -g to set globally, for all your repos)
git config set push.default upstream

Working with existing pull requests

You can fetch any pull request (fork-based or AGit-created), by knowing its number and choosing a local branch name (no need to add a new remote):

# replace 3 with the pull request number
# replace local-branch with your chosen branch name (will be created)
git fetch origin refs/pull/3/head:local-branch

# tell git that pull to this branch should fetch from the same pull request
git config set branch.local-branch.merge refs/pull/3/head

If the pull request was created using the AGit-flow (see below), the pull request creator and the users with repository writing rights can push to this ref, after setting the remote:

# tell git to push to origin refs/pull/3/head (see branch.local-branch.merge above)
git config set branch.local-branch.remote origin

With the 3 steps above, allowed users can now run git pull, git push and git push --force against AGit-pull requests.

Creating pull requests

AGit pull request creation requires a dedicated topic (branch-like name), which will be visible online (prefixed with username/) and used to associate further commits with the same pull request.

After choosing the target branch of your pull request (main usually), you can push your changes and create a pull request in one command:

# replace main with the target branch
# replace humble-feature with your topic
git push origin HEAD:refs/for/main/humble-feature

The HEAD part of the refspec refers to the checked out reference, but can be replaced with any “local ref”, like a local branch name (e.g. my-new-feature):

git push origin my-new-feature:refs/for/main/humble-feature

Setting a title and a description in AGit

It is possible to set additional parameters via git push options, such as title and description. Here’s another example targeting the dev branch:

git push origin HEAD:refs/for/dev/implement-part12 \
  -o title="Title of the PR" \
  -o description="This can be **any** markdown content."

Both push options are optional. If no title or description push option is included, the title and the description of the first commit will be used instead.

New lines are not supported in the description push option. Multi-line descriptions can be encoded in base64 and prefixed with {base64} to work around this:

# encode the content of the file pr-description.md to base64
# for a description with multiple lines
git push origin HEAD:refs/for/main/cron \
  -o title="Update registry data" \
  -o description="{base64}$(base64 -w0 ./pr-description.md)"

Updating an existing AGit pull request

To not have to specify the refspec for later pushes, you should configure my-new-feature branch in git:

# replace my-new-feature with your current branch name
# replace 4 with the pull request number
git config set branch.my-new-feature.merge refs/pull/4/head
git config set branch.my-new-feature.remote origin

This will enable running git pull and git push, as well as their variants like git pull --rebase or git push --force (--force-with-lease is unsupported though).

Programmatically creating (or updating) a pull request

If you wish to programmatically open pull requests (for instance in CI), you can use the credentials of any user allowed to open pull requests (no need for writing rights on the base repository).

# git clone
# do your thing (check for update, generate code ...) and abort if nothing new
# set write-credentials of the user (who may not have writing rights for this repository):
git remote set-url origin https://$FORGEJO_USERNAME:$ACCESS_TOKEN@codeberg.org/forgejo/forgejo.git
# git add ...
# git commit -m "new update"
git push origin HEAD:refs/for/main/data-update \
  -o title="Update data" \
  -o description="{base64}$(base64 -w0 ./pr-description.md)" \
  -o force-push="true"

If an AGit pull request from this user with this topic is still open, the content will be overridden (like a force-push), otherwise a new pull request will be opened. Without the force-push option, the workflow would fail if a previously created pull request was still open.

Parameters reference

git push <remote-name> <local-ref>:refs/<for|draft|for-review>/<branch>/<topic> [-o <topic|title|description|force-push>]

The following parameters are available:

• <remote-name>: The name of the remote repository (e.g., origin) (required)
• <local-ref>: The local reference being pushed (e.g., HEAD, my-branch, a commit hash) (required)
• refs/<for|draft|for-review>/<branch>/<topic>: Refspec (required)
  • for, draft, for-review: This parameter describes the pull request type. for opens a normal pull request. draft and for-review are currently silently ignored.
  • <branch>: The target branch that a pull request should be merged against (required)
  • <topic>: The topic for the remote pull request. If left empty, the topic must be supplied using the -o topic option.
• -o <topic|title|description|force-push>: Push options
  • topic: Essentially an identifier. If left empty, the value of <topic>, if present, will be used for the topic. Otherwise, Forgejo will return an error.
  • title: Title of the pull request. If left empty, the first line of the first new Git commit will be used instead.
  • description: Description of the pull request. If left empty, the description of the first new Git commit will be used instead.
  • force-push: Useless when the local branch has been configured. Historically necessary when rebasing, amending, or retroactively modifying your previous commits. Otherwise, a new pull request will be opened, even if you use the same topic. If used, the value of this parameter should be set to true.

For Gerrit users: Forgejo does not support Gerrit’s Change-Ids.

Review Workflow

The web UI can be used to review AGit pull requests like any other.

To get command line instructions, click the “View command line instructions” drop-down at the bottom of the pull request form.