Skip to content

Commit

Permalink
feat: add information for schedules (go-vela#366)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jbrockopp
jbrockopp authored Jul 24, 2023
1 parent 713f0ef commit 03ababe
Show file tree
Hide file tree
Showing 17 changed files with 968 additions and 17 deletions.
4 changes: 2 additions & 2 deletions .github/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Please see our [support](SUPPORT.md) documentation for further instructions.
## Copyright and License

```
Copyright (c) 2022 Target Brands, Inc.
Copyright (c) 2023 Target Brands, Inc.
```

[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
4 changes: 2 additions & 2 deletions LICENSE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@
same "printed page" as the copyright notice for easier
identification within third-party archives.

Copyright (c) 2022 Target Brands, Inc.
Copyright (c) 2023 Target Brands, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand All @@ -198,4 +198,4 @@
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
limitations under the License.
22 changes: 21 additions & 1 deletion content/installation/server/reference/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,26 @@ The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,m
By default, no repositories are allowed to be enabled. To allow any repository to be enabled, provide a single value of `*`.
{{% /alert %}}

### VELA_SCHEDULE_ALLOWLIST

This variable sets a group of repositories, from the SCM, that can create a schedule for a repo on the server.

The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,myOrg1/myRepo2,myOrg2/*`).

{{% alert title="Note:" color="primary" %}}
By default, no repositories are allowed to create a schedule. To allow any repository to create a schedule, provide a single value of `*`.
{{% /alert %}}

### VELA_SCHEDULE_MINIMUM_FREQUENCY

This variable sets the minimum frequency allowed to be set for a schedule.

The variable can be provided as a `duration` (i.e. `5s`, `10m`).

{{% alert title="Note:" color="primary" %}}
This variable has a default value of `1h`.
{{% /alert %}}

### VELA_SCM_ADDR

This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server.
Expand Down Expand Up @@ -690,4 +710,4 @@ The variable can be provided as a `duration` (i.e. `5s`, `10m`).
This variable has a default value of `5m`.\
\
The value should coordinate with the [`VELA_CHECK_IN`](/docs/installation/worker/reference/#vela_check_in) setting provided to the [worker](/docs/installation/worker/).
{{% /alert %}}
{{% /alert %}}
14 changes: 14 additions & 0 deletions content/reference/api/schedule/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: "Schedule"
linkTitle: "Schedule"
description: >
Learn how to use API endpoints for the schedule resource.
---

The below endpoints are available to operate on the `schedule` resource.

{{% alert color="warning" %}}
This section assumes you already know how to authenticate to the API.

To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
{{% /alert %}}
78 changes: 78 additions & 0 deletions content/reference/api/schedule/add.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
title: "Add"
linkTitle: "Add"
description: >
Learn how to create a schedule.
---

## Endpoint

```
POST /api/v1/schedules/:org/:repo
```

## Parameters

The following parameters are used to configure the endpoint:

| Name | Description |
|--------|----------------------|
| `org` | name of organization |
| `repo` | name of repository |

## Permissions

COMING SOON!

## Responses

| Status Code | Description |
|-------------|-----------------------------------------------------|
| `200` | indicates the request has succeeded |
| `401` | indicates the user does not have proper permissions |

## Sample

{{% alert color="warning" %}}
This section assumes you already know how to authenticate to the API.

To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
{{% /alert %}}

#### File

```json
{
"name": "hourly",
"entry": "0 * * * *",
"active": true
}
```

#### Request

```sh
curl \
-X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d "@data.json" \
"http://127.0.0.1:8080/api/v1/schedules/github/octocat"
```

#### Response

```json
{
"id": 1,
"repo_id": 1,
"active": true,
"name": "hourly",
"entry": "0 * * * *",
"created_at": 1641314085,
"created_by": "octokitty",
"updated_at": 1641314085,
"updated_by": "octokitty",
"scheduled_at": 0
}
```
83 changes: 83 additions & 0 deletions content/reference/api/schedule/get.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
title: "Get"
linkTitle: "Get"
description: >
Learn how to list schedules.
---

## Endpoint

```
GET /api/v1/schedules/:org/:repo
```

## Parameters

The following parameters are used to configure the endpoint:

| Name | Description |
|--------|----------------------|
| `org` | name of organization |
| `repo` | name of repository |

## Permissions

COMING SOON!

## Responses

| Status Code | Description |
|-------------|-----------------------------------------------------|
| `200` | indicates the request has succeeded |
| `400` | unable to retrieve the schedules |
| `401` | indicates the user does not have proper permissions |
| `404` | unable to retrieve the schedules |
| `500` | system error while retrieving the schedules |

## Sample

{{% alert color="warning" %}}
This section assumes you already know how to authenticate to the API.

To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
{{% /alert %}}

#### Request

```sh
curl \
-X GET \
-H "Authorization: Bearer <token>" \
"http://127.0.0.1:8080/api/v1/schedules/github/octocat"
```

#### Response

```json
[
{
"id": 2,
"repo_id": 1,
"active": true,
"name": "nightly",
"entry": "0 0 * * *",
"created_at": 1641314086,
"created_by": "octokitty",
"updated_at": 1641314086,
"updated_by": "octokitty",
"scheduled_at": 0
},
{
"id": 1,
"repo_id": 1,
"active": true,
"name": "hourly",
"entry": "0 * * * *",
"created_at": 1641314085,
"created_by": "octokitty",
"updated_at": 1641314085,
"updated_by": "octokitty",
"scheduled_at": 0
}
]
```
56 changes: 56 additions & 0 deletions content/reference/api/schedule/remove.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "Remove"
linkTitle: "Remove"
description: >
Learn how to delete a schedule.
---

## Endpoint

```
DELETE /api/v1/schedules/:org/:repo/:schedule
```

## Parameters

The following parameters are used to configure the endpoint:

| Name | Description |
|------------|----------------------------------|
| `org` | name of organization |
| `repo` | name of repository |
| `schedule` | name of schedule from repository |

## Permissions

COMING SOON!

## Responses

| Status Code | Description |
|-------------|-----------------------------------------------------|
| `200` | indicates the request has succeeded |
| `401` | indicates the user does not have proper permissions |

## Sample

{{% alert color="warning" %}}
This section assumes you already know how to authenticate to the API.

To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
{{% /alert %}}

#### Request

```sh
curl \
-X DELETE \
-H "Authorization: Bearer <token>" \
"http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly"
```

#### Response

```sh
schedule "hourly" deleted
```
77 changes: 77 additions & 0 deletions content/reference/api/schedule/update.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
title: "Update"
linkTitle: "Update"
description: >
Learn how to modify a schedule.
---

## Endpoint

```
PUT /api/v1/schedules/:org/:repo/:schedule
```

## Parameters

The following parameters are used to configure the endpoint:

| Name | Description |
|------------|----------------------------------|
| `org` | name of organization |
| `repo` | name of repository |
| `schedule` | name of schedule from repository |

## Permissions

COMING SOON!

## Responses

| Status Code | Description |
|-------------|-----------------------------------------------------|
| `200` | indicates the request has succeeded |
| `401` | indicates the user does not have proper permissions |

## Sample

{{% alert color="warning" %}}
This section assumes you already know how to authenticate to the API.

To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
{{% /alert %}}

#### File

```json
{
"active": false
}
```

#### Request

```sh
curl \
-X PUT \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d "@data.json" \
"http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly"
```

#### Response

```json
{
"id": 1,
"repo_id": 1,
"active": false,
"name": "hourly",
"entry": "0 * * * *",
"created_at": 1641314085,
"created_by": "octokitty",
"updated_at": 1641314086,
"updated_by": "octokitty",
"scheduled_at": 0
}
```
Loading

0 comments on commit 03ababe

Please sign in to comment.