Pipeline-level hooks
Problem to solve
It's difficult for an API user to get notified when their pipelines finish.
A user (or third-party application) with Developer access can create a pipeline through the Pipeline API but cannot be updated by a project hook when the pipeline finishes as the Project Hook API requires Maintainer-level permissions (source).
Intended users
Further details
My use case is an Alexa skill that allows users to trigger GitLab Pipelines using their voice (here's the project's source). Here's an example dialog:
User: Alexa, ask Lab Assistant to run a new deployment pipeline.
Alexa: Sure, would you like me to notify you when the pipeline finishes?
User: Yes, please.
Alexa: Done! I created a new deployment pipeline and will notify you when it finishes.
Provided the user has Developer permissions, the skill will create a new pipeline using the Pipeline API. However, I don't currently have a (good) way to detect when the pipeline finishes. With the current API, I have three options:
- Add a project hook that will call back to my skill when the pipeline finishes. This option isn't ideal as it will only work for users with Maintainer-level access or higher.
- Poll the Pipeline API for changes to the pipeline's status. This approach has two drawbacks:
- Polling is a messier and more resource-intensive solution that a webhook.
- In my specific case, I only have access to the user's OAuth token while the user is interacting with my skill. This means polling is not an option for me as I am unable to make API calls after the user finishes interacting with Alexa.
- Update the project's
.gitlab-ci.yml
to include a webhook-like step at the end. This option isn't ideal as it requires users to change their project configuration in order to integrate with my skill.
Proposal
Add a new concept of a pipeline-level hook. This hook would be associated with a specific pipeline and would be called when the pipeline finishes.
The hook could be created at pipeline creation time like this:
POST /projects/12345/pipeline?ref=master
{
"variables": [ ... ]
"hook": {
"url": "https://example.com/my-endpoint",
"enable_ssl_verification": true,
"token": "my_secret_token"
}
}
and/or after the pipeline has been created:
POST /projects/12345/pipeline/678910/hook
{
"url": "https://example.com/my-endpoint",
"enable_ssl_verification": true,
"token": "my_secret_token"
}
Permissions and Security
The permissions required to create a pipeline-level hook should be the same as the permissions required to create a pipeline.
Documentation
The Pipeline API documentation would need to be updated to include information about this new feature.
What is the type of buyer?
Ideally this feature would be made available to the self-managed/core users.