recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Diffusion User Guide: Permanent Refs
2@group userguide
3
4Explains when Diffusion will take actions in response to discovering commits.
5
6Overview
7========
8
9Diffusion can close tasks and revisions and take other actions when commits
10appear in a repository (either because they were pushed to Phorge, or
11because they were pushed to some remote which Phorge is observing).
12
13This document explains when Diffusion acts on commits and how to configure this
14behavior.
15
16
17Publishing Commits
18==================
19
20Diffusion distinguishes between "pushed" and "published" commits.
21
22Not all commits that are pushed to a repository are destined for greatness:
23for example, many tools push temporary commits to secret places like
24`refs/pull/123`, `refs/notes/*`, or `refs/changes/12/345678/1`.
25
26Sometimes, human users intentionally push changes to branches like
27"tmp-hack-ignore-123". This is formally discouraged by Phorge, but the
28practice is so widespread that we've given up trying to stop anyone from doing
29it.
30
31Phorge will import these commits and create pages for them so you can view
32them in the web UI and link to them, but does not take any other actions until
33they are "published".
34
35A commit is "published" when it becomes reachable from a permanent ref. By
36default, all branches are permanent refs, so pushing a commit to "master" will
37publish it, but pushing a commit to `refs/pull/123` (either directly, or by
38using a tool like GitHub) will not.
39
40Usually, commits are published by pushing them directly to a permanent branch
41like "master", or by merging a temporary branch into a permanent branch.
42
43When a commit is published, Phorge acts on it and:
44
45 - sends email;
46 - delivers notifications;
47 - publishes a feed story;
48 - triggers Audits;
49 - runs Herald rules;
50 - updates mentioned objects;
51 - closes referenced tasks; and
52 - closes associated revisions.
53
54
55Configuring Repositories
56========================
57
58You can control publishing behavior in two primary ways: by configuring
59which refs are considered to be permanent refs, and by disabling publishing
60entirely.
61
62By default, all branches are considered permanent refs and all other refs
63(including tags and other arbitrary custom refs) are considered nonpermanent.
64This means that, by default, pushing commits to a branch like
65"tmp-hack-ignore-123" will publish those commits.
66
67If you want to be free to push commits to temporary branches like this and
68only want commits on certain branches (like "master") to be published,
69configure which refs are treated as permanent by editing
70{nav Branches > Permanent Refs} from the "Manage" page of the repository.
71
72To disable publishing entirely, select {nav Basics > Disable Publishing}.
73
74
75Next Steps
76==========
77
78Continue by:
79
80 - troubleshooting in greater depth with
81 @{article:Troubleshooting Repository Imports}.