Gitea

https://docs.gitea.io/

특징

Webhooks

저장소 설정에 웹훅이 있다. 웹훅은 조직별로, 전체 시스템에 구성할 수도 있다. 모든 event pushes는 POST 요청이다.

지원 목록

• Gitea (can also be a GET request)
• Gogs
• Slack
• Discord
• Dingtalk
• Telegram
• Microsoft Teams
• Feishu
• Wechatwork
• Packagist

이벤트 정보

페이로드에서 secret 필드는 Gitea 1.14.0이후에 제거된다.

Gitea가 Payload URL에 보낼 이벤트 정보는 다음과 같다.

X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push

{
  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
  "ref": "refs/heads/develop",
  "before": "28e1879d029cb852e4844d9c718537df08844e03",
  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
  "commits": [
    {
      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
      "message": "Webhooks Yay!",
      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
      "author": {
        "name": "Gitea",
        "email": "someone@gitea.io",
        "username": "gitea"
      },
      "committer": {
        "name": "Gitea",
        "email": "someone@gitea.io",
        "username": "gitea"
      },
      "timestamp": "2017-03-13T13:52:11-04:00"
    }
  ],
  "repository": {
    "id": 140,
    "owner": {
      "id": 1,
      "login": "gitea",
      "full_name": "Gitea",
      "email": "someone@gitea.io",
      "avatar_url": "https://localhost:3000/avatars/1",
      "username": "gitea"
    },
    "name": "webhooks",
    "full_name": "gitea/webhooks",
    "description": "",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/gitea/webhooks",
    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
    "clone_url": "http://localhost:3000/gitea/webhooks.git",
    "website": "",
    "stars_count": 0,
    "forks_count": 1,
    "watchers_count": 1,
    "open_issues_count": 7,
    "default_branch": "master",
    "created_at": "2017-02-26T04:29:06-05:00",
    "updated_at": "2017-03-13T13:51:58-04:00"
  },
  "pusher": {
    "id": 1,
    "login": "gitea",
    "full_name": "Gitea",
    "email": "someone@gitea.io",
    "avatar_url": "https://localhost:3000/avatars/1",
    "username": "gitea"
  },
  "sender": {
    "id": 1,
    "login": "gitea",
    "full_name": "Gitea",
    "email": "someone@gitea.io",
    "avatar_url": "https://localhost:3000/avatars/1",
    "username": "gitea"
  }
}

예제

웹훅을 사용해서 저장소에 push 요청에 php 스크립트를 실행한다.

저장소 설정에서 "Webhook 추가"-"Gitea"를 누르고 다음과 같이 설정한다.

• Target URL: http://mydomain.com/webhook.php
• HTTP Method: POST
• POST Content Type: application/json
• Secret: 123
• Trigger On: Push Events
• Active: Checked

이제 서버에 webhook.php파일을 만들어라.

<?php

$secret_key = '123';

// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
    exit();
}

// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';

if ($content_type != 'application/json') {
    error_log('FAILED - not application/json - '. $content_type);
    exit();
}

// get payload
$payload = trim(file_get_contents("php://input"));

if (empty($payload)) {
    error_log('FAILED - no payload');
    exit();
}

// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';

if (empty($header_signature)) {
    error_log('FAILED - header signature missing');
    exit();
}

// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);

// check payload signature against header signature
if ($header_signature !== $payload_signature) {
    error_log('FAILED - payload signature');
    exit();
}

// convert json to array
$decoded = json_decode($payload, true);

// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
    error_log('FAILED - json decode - '. json_last_error());
    exit();
}

// success, do something

웹훅 리스트에서 들어가면 "전달 시험" 버튼이 있다.

개발자

API

API 접근 활성화/설정

기본적으로 ENABLE_SWAGGER는 true이고, MAX_RESPONSE_ITEMS는 50으로 설정되어 있다.

인증

Gitea는 API인증에 다음 methods를 제공한다.

• HTTP basic authentication
• token=... parameter in URL query string
• access_token=... parameter in URL query string
• Authorization: token ... header in HTTP headers

모든 methods는 같은 API key token type을 수락한다. Gitea는 modules/auth/auth.go에서 그 토큰을 찾기 위해 querys와 headers를 파싱한다. 코드를 봐야 이해하기가 낫다.

생성과 API tokens 리스팅

웹 페이지 사용자 설정에서 "어플리케이션"에 "토큰 생성"이 있다.

혹은 새로운 토큰은 /users/:name/tokens에 POST요청으로 생성할 수 있다.

/users/:name/tokens는 특별한 endpoint이고 BasicAuth와 비밀번호를 사용해서 인증해야 한다.

$ curl -XPOST -H "Content-Type: application/json"  -k -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}

( sha1토큰)은 한 번만 반환되며 일반 텍스트로 저장되지 않습니다. GET 요청이 있는 토큰을 나열할 때 표시되지 않습니다 .

$ curl --request GET --url https://yourusername:password@gitea.your.host/api/v1/users/<username>/tokens
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]

기본 인증을 사용하기 위해서는 two factor 인증이 활성화되어 있어야 하고 one time password가 포함된 헤더를 추가로 보내야 한다.

$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens

API 가이드

API Reference 가이드는 swagger에 의해 자동으로 생성된다.

https://gitea.your.host/api/swagger 나 Gitea demo instance 에서 볼 수 있다.

Sudo

sudo= 파라미터나(GET방식) Sudo: 요청 헤더를 username과 함께 추가해라.

SDKs

• Official go-sdk