GitHub Integration

Connect a repository to a project, read its pull requests in Elixion, and let merges move issues

Connecting a repository is what turns Elixion, the platform for Engineering Intelligence™, from a tracker into a place where delivery is visible. It is also the prerequisite for assigning an issue to an agent: until a project has a repository, agent options on an issue's assignee list stay disabled.

A repository is connected per project.

Connecting a repository

  1. Open Project Settings and pick the Integrations tab.
  2. Choose GitHub and open the connect dialog.
  3. Fill in three fields:
    • Repository URL, for example https://github.com/acme/payments.
    • Personal Access Token.
    • Default Branch, for example main.
  4. Connect.

Elixion validates the token against that repository before it stores anything. If the token cannot read the repository you get a specific reason rather than a generic failure, including the case GitHub itself is ambiguous about: a repository that does not exist and one your token may not see return the same answer from GitHub, and the error says so instead of guessing.

Token permissions

The dialog asks for:

  • repo, full repository access. Required.
  • read:user, read your profile. Optional.

A fine grained token must list the repository explicitly.

More than one repository

A project can hold several repositories, one connect call each. Connecting a URL that is already on the project is treated as a reconnect: the new token is validated and replaces the old one, and the existing configuration is kept.

The GitHub workspace

/github is the repository view inside Elixion. Pick a repository and you get four tabs:

  • Pull requests, filterable by state, with checks and merge conflict state, and the ability to merge from here.
  • Branches
  • Commits
  • Workflows, the GitHub Actions runs. For a GitLab repository this tab reads Pipelines.

Above the tabs, a repository status card shows whether the connection is healthy, with a reconnect action when it is not.

What a merged pull request does

This is the most useful automatic behaviour in the integration, and it is worth knowing exactly how it decides.

Where Elixion looks for an issue key. The pull request's title and its head branch name. Nothing else: not the body, not the commit messages.

How it matches. It looks for the project's own key followed by a number, case insensitively. A branch called fix/pay-42-refund-rounding and a title reading Correct refund rounding (PAY-42) both match PAY-42.

What it does with a match. Every matched issue that is not already Done or Deferred moves to In Review and is assigned back to its reporter for acceptance, and a comment is posted on the issue saying the move happened because that pull request merged.

Two consequences worth stating plainly:

  • There are no keywords. Fixes, Closes, Related to and the rest carry no special meaning. Every key found is treated the same way.
  • A merge never sets an issue to Done. Acceptance belongs to a person, so the automation stops at In Review.

Several keys in one title link several issues, and all of them move.

This behaviour is on by default and is controlled by the integration's own configuration.

Auto-merging when an issue reaches Done

The reverse direction is opt-in. On the project's Integrations tab, each connected repository carries a switch, Auto-merge pull requests when an issue is moved to Done, with a merge method beside it (squash, merge commit, or rebase; squash by default). With it on, the flow for agent work is: the agent opens a pull request and the issue moves to In Review; a person reviews the pull request and moves the issue to Done; Elixion then merges that pull request, provided GitHub reports it mergeable with its checks green. If the checks fail, or the branch conflicts and Elixion cannot bring it up to date, nothing is merged and a comment on the issue says why, so a pull request is never merged behind a red build. The switch is off for every repository until someone turns it on, because a merge is the one step in this pipeline that cannot be undone.

Delivery evidence on the issue

An issue's Delivery section carries two lists:

  • Evidence. Pull requests with their merge state, commits, test runs with pass or fail, artifacts and links. Each row shows whether an agent recorded it or a person did.
  • Runs. What ran against this issue, when, how it ended, and whether the record came from the platform or from an agent reporting on itself.

An issue also carries a branch name field and a pull request URL of its own, shown in its properties panel.

Previews on the issue

When a deployment reports its status for a branch that names an issue, Elixion records a preview on that issue and shows it on the issue page above the Delivery lists.

A deployment names its issue in one of two ways, and both are checked: the branch carries the issue key, for example feature/PAY-42-add-currency, or the issue records that branch in its branch name field.

The preview follows the deployment's state:

| Deployment state | What the issue shows | |------------------|----------------------| | queued, pending, in_progress | Building | | success | Ready, with the link | | failure, error | Failed | | inactive | Ready, with the time it stopped being live | | anything else | A preview exists, without claiming it is ready |

One preview is kept per environment, so a redeploy to the same environment updates the row rather than adding another. A preview link that is not an ordinary web address is dropped rather than shown.

The card also carries the size of the change, taken from the pull request: files changed, lines added, lines removed, and the time those numbers were read. The numbers describe the pull request as Elixion last saw it, not necessarily as it stands this second.

Two way issue sync

Separately from pull request handling, GitHub Issues can be synchronised with Elixion issues. Configure it from the Sync Status tab on the project's Integrations page, through Configure Sync.

| Setting | Options | |---------|---------| | Sync Direction | Bi-directional, Push only (Elixion to GitHub), Pull only (GitHub to Elixion) | | Sync automatically | Off by default. When on, changes are pushed as issues are created and updated. This is event driven, not a timer | | Sync Frequency | Manual only, every 5 minutes, every 15 minutes, every hour, or once a day. This is the timer, and it is a different switch from the one above | | Data to Sync | Issues and tasks, comments, attachments, status changes, labels | | Conflict Resolution | Latest change wins, Elixion always wins, External always wins, or Manual resolution |

With Manual resolution, conflicts are listed for you to settle one at a time.

Each scheduled run is recorded in the Activity Logs tab, alongside webhook deliveries. Pressing Sync runs the same handler on demand.

Inbound webhook events

Elixion acts on four GitHub event types:

  • issues
  • pull_request
  • push
  • deployment_status

Other events are accepted and ignored. Continuous integration results are visible on the Workflows tab of /github rather than written onto an issue.

deployment_status is what puts a preview on an issue. A webhook created before preview support existed will not be subscribed to it, and Elixion does not change the events on a webhook you created. If previews never appear, check the event list on the webhook itself first.

Troubleshooting

No preview appears on an issue, though the deployment succeeded. Check that the repository's webhook is subscribed to deployment_status. A webhook created before preview support existed is not subscribed to it, and Elixion does not modify the events on a webhook you created. Then check that the branch names the issue, either by carrying its key or by matching the issue's branch name field.

The connect dialog rejects my token. The message names the cause. The common ones are a token without repo, a fine grained token that does not list this repository, and a repository name that does not match.

A merged pull request did not move its issue. Check that the key is in the title or the branch name, that it uses this project's key, and that the issue was not already Done or Deferred.

Agent options are disabled on the assignee list. The project has no repository connected. Connect one first.

A sync ran but nothing changed. Check the direction. Push only and Pull only each move changes one way, and the Activity Logs tab records what each run did.

Next