# Tickets library

## Ticket reference check

Fails a feature branch's build unless the branch can be tied to a Jira ticket.
`cloud_build_only` and `cloud_deployment` run it in their Check stage, after
the commit check.

A build passes when an existing ticket key, in capitals (e.g. `APD-123`), is in
any of these, checked in this order:

1. the branch name
2. a commit on the branch that isn't on the main branch
3. the title of the branch's open pull request; declined, merged and
   superseded pull requests don't count

Builds of the main branch are not checked. The result is reported to Bitbucket
as the **Ticket reference** build status, which says what was missing when the
build fails.

If Bitbucket can't be read and no key was found elsewhere, the build is marked
UNSTABLE instead of failing, so a Bitbucket outage doesn't block builds.

Builds run when commits are pushed, not when a pull request's title changes.
After fixing a title, re-run the build.

### Credentials

| Credential | Used for |
|---|---|
| `bitbucket_oauth` | Reading the branch's commits and its open pull request. The OAuth consumer needs read access to repositories and pull requests. |
| `jenkins-jira` | Confirming each key exists. A key Jira reports as missing doesn't count. If Jira can't be reached, keys count without confirmation. |

### Signature

`tickets.check_reference(String main_branch = "master")`

*Parameter*

- `main_branch` is the repository's main branch, e.g. `main`. Builds of it are
  not checked, and commits already on it don't count. (Optional, defaults to
  `master`)

### Examples

```groovy
stage("Check") {
    steps {
        script {
            tickets.check_reference()
        }
    }
}
```

For a repository whose main branch is `main`:

```groovy
tickets.check_reference("main")
```