FireHydrant has a powerful change event functionality that allows storing any event that occurs in your system and easily finding it later. Change events get even more powerful when you can link them together, though. FireHydrant allows you to loosely link change events together using something we call "Change Identities".

How Change Identities Work

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

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 to 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 will create a change event in FireHydrant with the commit sha as an identity.


When you include an identity, a "Change" is also created that will contain all of the linked change events, which you can see in the bottom of the above screenshot.

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

Upon success, a new change event is created.

This creates a change event just like the previous request, however, we can see that this change event was automatically linked to our previous change. If we click the "Test Suite Ran" link in the bottom, we're taken to a timeline view of all change events.

Now, finally, 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 incredibly valuable because as a change moves through a pipeline, different stages have different contexts. For a CI pipeline, it's usually able to get the commit sha that is being built, 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 things loosely together. Let's create a third change event with only our docker image tag to demonstrate.

$ 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, you can see we're only including the "image" identity that matches the second change event we sent. FireHydrant will then link this together to the others and include it in your grouped change view.

Voila! FireHydrant has successfully linked all of the change events together in a single change group by using the identities you pass along. Our API is a great way to do this, but we recommend using our fhcli tool to send things from your continuous integration tool, which you can read about 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, head here.

Did this answer your question?