Change Events and Identities

FireHydrant has a powerful change event functionality that allows you to store events that occur in your system and easily find them later. Change events become even more powerful when you can link them together. FireHydrant enables you to loosely link change events together using what we call Change Identities.

How Change Identities Work

When you create a change event via the FireHydrant API, you can send a key with it, called change_identities. You might send a change event from your continuous integration system, and another from your deployment system. From both of these, you can send a uniquely identifying change event, and also include an identity that might have been created by the previous step in your pipeline.

Sending a change event

For example, your test runner can send a change event and include an identity value of commit_sha with a value of abc123 (change events can have multiple identities associated with them). When your test suite completes, using cURL, we can send a change event with the commit sha as an identity:

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Finished Test Run",
    "starts_at": "2019-05-07T08:00:00",
    "change_identities": [
      {
        "type": "commit_sha",
        "value": "abcdef123456789"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

This creates a change event in FireHydrant with the commit sha as an identity.
When you include an identity, a Change is also created containing all of the linked change events.

Note: The value for each type in a change identity must be unique for a given change event. Duplicate values will be silently dropped. If you have types that may reasonably contain duplicate values,authorandreviewerfor instance,  consider using alabelinstead.

Linking change events using an identity

Now, let's create another change event, with the same change identity, but also include another identity for a Docker image tag.

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{ 
    "summary": "Built Docker Image",
    "starts_at": "2019-05-07T08:00:00",
    "change_identities": [
      {
        "type": "commit_sha",
        "value": "abcdef123456780"
      },
      {
        "type": "image",
        "value": "registry.firehydrant.io/firehydrant/laddertruck:master-abcdef123456789"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

The above cURL snippet creates a change event just like the previous request; however, this new change event is also automatically linked to our previous change.
All associated change events are cited (and linked) in the Associated Changes section at the bottom of the page.

Loosely linking change events using partial identity

Now, we can loosely link another change event in our deployment pipeline by only including a partial overlap of another change event's identities.

This is a valuable option, because as a change moves through a pipeline, different stages have different contexts. With a CI pipeline, you can usually get the commit sha; but for a deployment to a server, you may only know the artifact name (such as a Docker image or tarball name). By including previous identities, we can link events loosely together.

Let's create another change event with only our Docker image:

$ curl -X POST -H "Authorization: Bearer fhb-your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Deployed to Kubernetes (Production)",
    "starts_at": "2019-05-07T09:10:00",
    "change_identities": [
      {
        "type": "image",
        "value": "registry.firehydrant.io/firehydrant/laddertruck:master-abcdef123456700"
      }
    ]
  }' https://api.firehydrant.io/v1/changes/events

In this example, we're only including the "image" identity that matches the previous change event we sent. FireHydrant links this event this together to the others and includes it in your grouped change view.

Sending events from the FireHydrant CLI

Using FireHydrant's API is a great way to link change events, but we recommend using our fhcli tool to send things from your continuous integration tool. You can read more about the CLI tool here.

If you're deploying to Kubernetes, change events are automatically sent to FireHydrant with an identity of image, meaning you can easily link from your Docker builds and pushes. To learn more about our Kubernetes integration, go here.