Skip to content

G
gitlab-ce
Commit dd6c69e6 authored by Douwe Maan's avatar Douwe Maan Committed by Robert Speicher
Browse files
Options

Merge branch 'ci/api-builds' into 'master' 

Add builds API

References #4264

See merge request !2207
parent 2a89073c
Hide whitespace changes
Inline Side-by-side
Showing with 724 additions and 0 deletions
CHANGELOG
View file @ dd6c69e6
...@@ -44,6 +44,7 @@ v 8.4.0 (unreleased) ...@@ -44,6 +44,7 @@ v 8.4.0 (unreleased)
- Allow subsequent validations in CI Linter - Allow subsequent validations in CI Linter
- Show referenced MRs & Issues only when the current viewer can access them - Show referenced MRs & Issues only when the current viewer can access them
- Fix Encoding::CompatibilityError bug when markdown content has some complex URL (Jason Lee) - Fix Encoding::CompatibilityError bug when markdown content has some complex URL (Jason Lee)
- Add API support for managing builds of a project
- Add API support for managing build variables of project - Add API support for managing build variables of project
- Allow broadcast messages to be edited - Allow broadcast messages to be edited
......
app/models/commit_status.rb
View file @ dd6c69e6
...@@ -56,6 +56,8 @@ class CommitStatus < ActiveRecord::Base ...@@ -56,6 +56,8 @@ class CommitStatus < ActiveRecord::Base
scope :ordered, -> { order(:ref, :stage_idx, :name) } scope :ordered, -> { order(:ref, :stage_idx, :name) }
scope :for_ref, ->(ref) { where(ref: ref) } scope :for_ref, ->(ref) { where(ref: ref) }
AVAILABLE_STATUSES = ['pending', 'running', 'success', 'failed', 'canceled']
state_machine :status, initial: :pending do state_machine :status, initial: :pending do
event :run do event :run do
transition pending: :running transition pending: :running
......
doc/api/README.md
View file @ dd6c69e6
...@@ -23,6 +23,7 @@ ...@@ -23,6 +23,7 @@
- [Namespaces](namespaces.md) - [Namespaces](namespaces.md)
- [Settings](settings.md) - [Settings](settings.md)
- [Keys](keys.md) - [Keys](keys.md)
- [Builds](builds.md)
- [Build Variables](build_variables.md) - [Build Variables](build_variables.md)
## Clients ## Clients
......
doc/api/builds.md 0 → 100644
View file @ dd6c69e6
# Builds API
## List project builds
Get a list of builds in a project.
```
GET /projects/:id/builds
```
### Parameters
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| id | integer | yes | The ID of a project |
| scope | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
### Example of request
```
curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
```
### Example of response
```json
[
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2015-12-24T15:51:21.802Z",
"download_url": null,
"finished_at": "2015-12-24T17:54:27.895Z",
"id": 7,
"name": "teaspoon",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": "2015-12-24T17:54:27.722Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
},
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2015-12-24T15:51:21.727Z",
"download_url": null,
"finished_at": "2015-12-24T17:54:24.921Z",
"id": 6,
"name": "spinach:other",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": "2015-12-24T17:54:24.729Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
}
]
```
## List commit builds
Get a list of builds for specific commit in a project.
```
GET /projects/:id/repository/commits/:sha/builds
```
### Parameters
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| id | integer | yes | The ID of a project |
| sha | string | yes | The SHA id of a commit |
| scope | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
### Example of request
```
curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
```
### Example of response
```json
[
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2016-01-11T10:13:33.506Z",
"download_url": null,
"finished_at": "2016-01-11T10:14:09.526Z",
"id": 69,
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": null,
"status": "canceled",
"tag": false,
"user": null
},
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2015-12-24T15:51:21.957Z",
"download_url": null,
"finished_at": "2015-12-24T17:54:33.913Z",
"id": 9,
"name": "brakeman",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": "2015-12-24T17:54:33.727Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
}
]
```
## Get a single build
Get a single build of a project
```
GET /projects/:id/builds/:build_id
```
### Parameters
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| id | integer | yes | The ID of a project |
| build\_id | integer | yes | The ID of a build |
### Example of request
```
curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
```
### Example of response
```json
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2015-12-24T15:51:21.880Z",
"download_url": null,
"finished_at": "2015-12-24T17:54:31.198Z",
"id": 8,
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": "2015-12-24T17:54:30.733Z",
"status": "failed",
"tag": false,
"user": {
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"bio": null,
"created_at": "2015-12-21T13:14:24.077Z",
"id": 1,
"is_admin": true,
"linkedin": "",
"name": "Administrator",
"skype": "",
"state": "active",
"twitter": "",
"username": "root",
"web_url": "http://gitlab.dev/u/root",
"website_url": ""
}
}
```
## Cancel a build
Cancel a single build of a project
```
POST /projects/:id/builds/:build_id/cancel
```
### Parameters
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| id | integer | yes | The ID of a project |
| build\_id | integer | yes | The ID of a build |
### Example of request
```
curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
```
### Example of response
```json
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2016-01-11T10:13:33.506Z",
"download_url": null,
"finished_at": "2016-01-11T10:14:09.526Z",
"id": 69,
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": null,
"status": "canceled",
"tag": false,
"user": null
}
```
## Retry a build
Retry a single build of a project
```
POST /projects/:id/builds/:build_id/retry
```
### Parameters
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| id | integer | yes | The ID of a project |
| build\_id | integer | yes | The ID of a build |
### Example of request
```
curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
```
### Example of response
```json
{
"commit": {
"author_email": "admin@example.com",
"author_name": "Administrator",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "Test the CI integration.",
"short_id": "0ff3ae19",
"title": "Test the CI integration."
},
"coverage": null,
"created_at": "2016-01-11T10:13:33.506Z",
"download_url": null,
"finished_at": null,
"id": 69,
"name": "rubocop",
"ref": "master",
"runner": null,
"stage": "test",
"started_at": null,
"status": "pending",
"tag": false,
"user": null
}
```
lib/api/api.rb
View file @ dd6c69e6
...@@ -54,6 +54,7 @@ module API ...@@ -54,6 +54,7 @@ module API
mount Keys mount Keys
mount Tags mount Tags
mount Triggers mount Triggers
mount Builds
mount Variables mount Variables
end end
end end
lib/api/builds.rb 0 → 100644
View file @ dd6c69e6
module API
# Projects builds API
class Builds < Grape::API
before { authenticate! }
resource :projects do
# Get a project builds
#
# Parameters:
# id (required) - The ID of a project
# scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
# if none provided showing all builds)
# Example Request:
# GET /projects/:id/builds
get ':id/builds' do
builds = user_project.builds.order('id DESC')
builds = filter_builds(builds, params[:scope])
present paginate(builds), with: Entities::Build,
user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
end
# Get builds for a specific commit of a project
#
# Parameters:
# id (required) - The ID of a project
# sha (required) - The SHA id of a commit
# scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
# if none provided showing all builds)
# Example Request:
# GET /projects/:id/repository/commits/:sha/builds
get ':id/repository/commits/:sha/builds' do
commit = user_project.ci_commits.find_by_sha(params[:sha])
return not_found! unless commit
builds = commit.builds.order('id DESC')
builds = filter_builds(builds, params[:scope])
present paginate(builds), with: Entities::Build,
user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
end
# Get a specific build of a project
#
# Parameters:
# id (required) - The ID of a project
# build_id (required) - The ID of a build
# Example Request:
# GET /projects/:id/builds/:build_id
get ':id/builds/:build_id' do
build = get_build(params[:build_id])
return not_found!(build) unless build
present build, with: Entities::Build,
user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
end
# Get a trace of a specific build of a project
#
# Parameters:
# id (required) - The ID of a project
# build_id (required) - The ID of a build
# Example Request:
# GET /projects/:id/build/:build_id/trace
#
# TODO: We should use `present_file!` and leave this implementation for backward compatibility (when build trace
# is saved in the DB instead of file). But before that, we need to consider how to replace the value of
# `runners_token` with some mask (like `xxxxxx`) when sending trace file directly by workhorse.
get ':id/builds/:build_id/trace' do
build = get_build(params[:build_id])
return not_found!(build) unless build
header 'Content-Disposition', "infile; filename=\"#{build.id}.log\""
content_type 'text/plain'
env['api.format'] = :binary
trace = build.trace
body trace
end
# Cancel a specific build of a project
#
# parameters:
# id (required) - the id of a project
# build_id (required) - the id of a build
# example request:
# post /projects/:id/build/:build_id/cancel
post ':id/builds/:build_id/cancel' do
authorize_manage_builds!
build = get_build(params[:build_id])
return not_found!(build) unless build
build.cancel
present build, with: Entities::Build,
user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
end
# Retry a specific build of a project
#
# parameters:
# id (required) - the id of a project
# build_id (required) - the id of a build
# example request:
# post /projects/:id/build/:build_id/retry
post ':id/builds/:build_id/retry' do
authorize_manage_builds!
build = get_build(params[:build_id])
return forbidden!('Build is not retryable') unless build && build.retryable?
build = Ci::Build.retry(build)
present build, with: Entities::Build,
user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
end
end
helpers do
def get_build(id)
user_project.builds.find_by(id: id.to_i)
end
def filter_builds(builds, scope)
return builds if scope.nil? || scope.empty?
available_statuses = ::CommitStatus::AVAILABLE_STATUSES
scope =
if scope.is_a?(String)
[scope]
elsif scope.is_a?(Hashie::Mash)
scope.values
else
['unknown']
end
unknown = scope - available_statuses
render_api_error!('Scope contains invalid value(s)', 400) unless unknown.empty?
builds.where(status: available_statuses && scope)
end
def authorize_manage_builds!
authorize! :manage_builds, user_project
end
end
end
end
lib/api/entities.rb
View file @ dd6c69e6
...@@ -367,6 +367,33 @@ module API ...@@ -367,6 +367,33 @@ module API
expose :id, :variables expose :id, :variables
end end
class Runner < Grape::Entity
expose :id
expose :description
expose :active
expose :is_shared
expose :name
end
class Build < Grape::Entity
expose :id, :status, :stage, :name, :ref, :tag, :coverage
expose :created_at, :started_at, :finished_at
expose :user, with: User
# TODO: download_url in Ci:Build model is an GitLab Web Interface URL, not API URL. We should think on some API
# for downloading of artifacts (see: https://gitlab.com/gitlab-org/gitlab-ce/issues/4255)
expose :download_url do |repo_obj, options|
if options[:user_can_download_artifacts]
repo_obj.download_url
end
end
expose :commit, with: RepoCommit do |repo_obj, _options|
if repo_obj.respond_to?(:commit)
repo_obj.commit.commit_data
end
end
expose :runner, with: Runner
end
class Variable < Grape::Entity class Variable < Grape::Entity
expose :key, :value expose :key, :value
end end
......
spec/factories/ci/builds.rb
View file @ dd6c69e6
...@@ -30,6 +30,7 @@ FactoryGirl.define do ...@@ -30,6 +30,7 @@ FactoryGirl.define do
name 'test' name 'test'
ref 'master' ref 'master'
tag false tag false
created_at 'Di 29. Okt 09:50:00 CET 2013'
started_at 'Di 29. Okt 09:51:28 CET 2013' started_at 'Di 29. Okt 09:51:28 CET 2013'
finished_at 'Di 29. Okt 09:53:28 CET 2013' finished_at 'Di 29. Okt 09:53:28 CET 2013'
commands 'ls -a' commands 'ls -a'
...@@ -42,6 +43,10 @@ FactoryGirl.define do ...@@ -42,6 +43,10 @@ FactoryGirl.define do
commit factory: :ci_commit commit factory: :ci_commit
trait :canceled do
status 'canceled'
end
after(:build) do |build, evaluator| after(:build) do |build, evaluator|
build.project = build.commit.project build.project = build.commit.project
end end
...@@ -54,5 +59,11 @@ FactoryGirl.define do ...@@ -54,5 +59,11 @@ FactoryGirl.define do
factory :ci_build_tag do factory :ci_build_tag do
tag true tag true
end end
factory :ci_build_with_trace do
after(:create) do |build, evaluator|
build.trace = 'BUILD TRACE'
end
end
end end
end end
spec/requests/api/builds_spec.rb 0 → 100644
View file @ dd6c69e6
require 'spec_helper'
describe API::API, api: true do
include ApiHelpers
let(:user) { create(:user) }
let(:user2) { create(:user) }
let!(:project) { create(:project, creator_id: user.id) }
let!(:developer) { create(:project_member, user: user, project: project, access_level: ProjectMember::DEVELOPER) }
let!(:reporter) { create(:project_member, user: user2, project: project, access_level: ProjectMember::REPORTER) }
let(:commit) { create(:ci_commit, project: project)}
let(:build) { create(:ci_build, commit: commit) }
let(:build_with_trace) { create(:ci_build_with_trace, commit: commit) }
let(:build_canceled) { create(:ci_build, :canceled, commit: commit) }
describe 'GET /projects/:id/builds ' do
context 'authorized user' do
it 'should return project builds' do
get api("/projects/#{project.id}/builds", user)
expect(response.status).to eq(200)
expect(json_response).to be_an Array
end
it 'should filter project with one scope element' do
get api("/projects/#{project.id}/builds?scope=pending", user)
expect(response.status).to eq(200)
expect(json_response).to be_an Array
end
it 'should filter project with array of scope elements' do
get api("/projects/#{project.id}/builds?scope[0]=pending&scope[1]=running", user)
expect(response.status).to eq(200)
expect(json_response).to be_an Array
end
it 'should respond 400 when scope contains invalid state' do
get api("/projects/#{project.id}/builds?scope[0]=pending&scope[1]=unknown_status", user)
expect(response.status).to eq(400)
end
end
context 'unauthorized user' do
it 'should not return project builds' do
get api("/projects/#{project.id}/builds")
expect(response.status).to eq(401)
end
end
end
describe 'GET /projects/:id/repository/commits/:sha/builds' do
context 'authorized user' do
it 'should return project builds for specific commit' do
project.ensure_ci_commit(commit.sha)
get api("/projects/#{project.id}/repository/commits/#{commit.sha}/builds", user)
expect(response.status).to eq(200)
expect(json_response).to be_an Array
end
end
context 'unauthorized user' do
it 'should not return project builds' do
project.ensure_ci_commit(commit.sha)
get api("/projects/#{project.id}/repository/commits/#{commit.sha}/builds")
expect(response.status).to eq(401)
end
end
end
describe 'GET /projects/:id/builds/:build_id' do
context 'authorized user' do
it 'should return specific build data' do
get api("/projects/#{project.id}/builds/#{build.id}", user)
expect(response.status).to eq(200)
expect(json_response['name']).to eq('test')
end
end
context 'unauthorized user' do
it 'should not return specific build data' do
get api("/projects/#{project.id}/builds/#{build.id}")
expect(response.status).to eq(401)
end
end
end
describe 'GET /projects/:id/builds/:build_id/trace' do
context 'authorized user' do
it 'should return specific build trace' do
get api("/projects/#{project.id}/builds/#{build_with_trace.id}/trace", user)
expect(response.status).to eq(200)
expect(response.body).to eq(build_with_trace.trace)
end
end
context 'unauthorized user' do
it 'should not return specific build trace' do
get api("/projects/#{project.id}/builds/#{build_with_trace.id}/trace")
expect(response.status).to eq(401)
end
end
end
describe 'POST /projects/:id/builds/:build_id/cancel' do
context 'authorized user' do
context 'user with :manage_builds persmission' do
it 'should cancel running or pending build' do
post api("/projects/#{project.id}/builds/#{build.id}/cancel", user)
expect(response.status).to eq(201)
expect(project.builds.first.status).to eq('canceled')
end
end
context 'user without :manage_builds permission' do
it 'should not cancel build' do
post api("/projects/#{project.id}/builds/#{build.id}/cancel", user2)
expect(response.status).to eq(403)
end
end
end
context 'unauthorized user' do
it 'should not cancel build' do
post api("/projects/#{project.id}/builds/#{build.id}/cancel")
expect(response.status).to eq(401)
end
end
end
describe 'POST /projects/:id/builds/:build_id/retry' do
context 'authorized user' do
context 'user with :manage_builds persmission' do
it 'should retry non-running build' do
post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry", user)
expect(response.status).to eq(201)
expect(project.builds.first.status).to eq('canceled')
expect(json_response['status']).to eq('pending')
end
end
context 'user without :manage_builds permission' do
it 'should not retry build' do
post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry", user2)
expect(response.status).to eq(403)
end
end
end
context 'unauthorized user' do
it 'should not retry build' do
post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry")
expect(response.status).to eq(401)
end
end
end
end
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7