gogs / docs-api

A repository for Gogs API v1 documentation.

简体中文

🔮 Vision

The Gogs (/gɑgz/) project aims to build a simple, stable and extensible self-hosted Git service that can be set up in the most painless way. With Go, this can be done with an independent binary distribution across all platforms that Go supports, including Linux, macOS, Windows and ARM-based systems.

📡 Overview

• Please visit our home page for user documentation.
• Please refer to CHANGELOG.md for list of changes in each releases.
• Want to try it before doing anything else? Do it online!
• Having trouble? Help yourself with troubleshooting or ask questions in Discussions.
• Want to help with localization? Check out the localization documentation.
• Ready to get hands dirty? Read our contributing guide.
• Hmm... What about APIs? We have experimental support with documentation.

💌 Features

• User dashboard, user profile and activity timeline.
• Access repositories via SSH, HTTP and HTTPS protocols.
• User, organization and repository management.
• Repository and organization webhooks, including Slack, Discord and Dingtalk.
• Repository Git hooks, deploy keys and Git LFS.
• Repository issues, pull requests, wiki, protected branches and collaboration.
• Migrate and mirror repositories with wiki from other code hosts.
• Web editor for quick editing repository files and wiki.
• Jupyter Notebook and PDF rendering.
• Authentication via SMTP, LDAP, reverse proxy, GitHub.com and GitHub Enterprise with 2FA.
• Customize HTML templates, static files and many others.
• Rich database backend, including PostgreSQL, MySQL, SQLite3 and TiDB.
• Have localization over 31 languages.

💾 Hardware requirements

• A Raspberry Pi or $5 Digital Ocean Droplet is more than enough to get you started. Some even use 64MB RAM Docker CaaS.
• 2 CPU cores and 512MB RAM would be the baseline for teamwork.
• Increase CPU cores when your team size gets significantly larger, memory footprint remains low.

💻 Browser support

• Please see Semantic UI for specific versions of supported browsers.
• The smallest resolution officially supported is 1024*768, however the UI may still look right in smaller resolutions, but no promises or fixes.

📜 Installation

Make sure you install the prerequisites first.

There are 6 ways to install Gogs:

• Install from binary
• Install from source
• Install from packages
• Ship with Docker
• Try with Vagrant

Deploy to cloud

• Cloudron
• Sandstorm
• sloppy.io
• YunoHost
• DPlatform
• LunaNode
• alwaysdata

Tutorials

• Private Git Web Portal in Raspberry PI With Gogs
• How To Set Up Gogs on Ubuntu 14.04
• Run your own GitHub-like service with the help of Docker
• Dockerized Gogs git server and alpine postgres in 20 minutes or less
• Host Your Own Private GitHub with Gogs
• 使用 Gogs 搭建自己的 Git 服务器 (Chinese)
• 阿里云上 Ubuntu 14.04 64 位安装 Gogs (Chinese)
• Installing Gogs on FreeBSD
• How to install Gogs on a Linux Server (DigitalOcean)

📦 Software, service and product support

• Fabric8 (DevOps)
• Jenkins (CI)
• Puppet (IT)
• Synology (Docker)
• Syncloud (App Store)

🙇‍♂️ Acknowledgments

This project is proundly supported by:

Other acknowledgments:

• Thanks Egon Elbre for designing the original version of the logo.
• Thanks Crowdin for sponsoring open source translation plan.
• Thanks MonoVM for sponsoring VPS services.
• Thanks Buildkite for sponsoring open source CI/CD plan.

👋 Contributors

• See contributors page for top 100 contributors.
• See TRANSLATORS for public list of translators.

⚖️ License

This project is under the MIT License. See the LICENSE file for the full license text.

docs-api's Issues

can not curl releases api

when call release api return 404 page.

I hopo get releases lists for repos.

the error result like the pic

use this config can get branch as well.

POST /orgs/:orgname (create an Org via REST API) 🙏

Greetings fellow Gogs Users! 👋
Our reading of the Organizations API Dos: https://github.com/gogs/docs-api/tree/master/Organizations
is that there is no way to create a new org ...

e.g:

POST /orgs/:orgname

We really want to be able to do this via the REST API for the App we are building.
Any help would be much appreciated.
Thanks.

Add docs for `GET /repos/:owner/:repo/contents/:path`

gogs/gogs#5963

I can't list all branches in one repo of one org

Hello,

I am using gogs very nice software.
I am using api and I can list all reports of one organization:

Now, if I want to list all branches of terraform repo I can't get JSON reponse:

I have tried multiple options:

http://mgcl1n1:3000/api/v1/orgs/ict/repos/ict/terraform/branches?access_token=blablabla
http://mgcl1n1:3000/api/v1/orgs/ict/repos/terraform/branches?access_token=blablabla

no one is working.
What is the correct call?

PUT /orgs/:orgname/memberships/:username

i request this api always return '404Not Found'
and the organizition is exists, the user also exists

How to create new branch in repo via CLI

i dont see any option/CLI that we can create new branch in repo.

Looking to publish release through Http request from Jenkins

Hi,

Looking to have jenkins publish a release after the build and test complete, I see the http command from the github api, but not from gogs.

Is this something that is implemented, but not with docs? Is there another way to achieve this goal besides http requests?

Thanks!

Error creating token

$ curl -X PORT -u USER:PASSWD --data '{"name":"USER"}' https://try.gogs.io/api/v1/users/rbranco/tokens
template: base/footer:15:47: executing "base/footer" at <.PageStartTime>: invalid value; expected time.Time

Prohibit login parameter

Method: Edit an existing user PATCH /admin/users/:username
Add optional parameter for login prohibit prohibit_login: bool

/repos/search api returns fewer responses than the "Explore" section

The official Gogs v1 /repos/search API seems to be returning fewer responses when compared to the "Explore" section.

For example:

• https://try.gogs.io/api/v1/repos/search?page=28&limit=20 suggests that the gogs instance has only 28 pages (page size = 20) since any page beyond this is empty. This suggests that try.gogs.io has 28 * 20 = 560 repos.
• But, the "Explore" section goes till page 685! https://try.gogs.io/explore/repos?page=685&q= (page size = 20). This suggests that try.gogs.io has 685 * 20 = 13700 repos.

So is there any implicit difference between these routes or is it a bug?

about 403 question

hi
url:http://192.168.60.175:3000/api/v1/admin/users/show/repos?token=b96ed14c42a1ed7f94c5d4e54d8e0ede0d7f9dad

response: 403Forbidden

I request that my local Gogs can add warehouses, but remote access to the server is not possible.

please tell me how can i solve this question.

thank you very much!

update api doc for DELETE `/repos/:username/:reponame/collaborators/:collaborator`

API Endpoint /repos/:username/:reponame/collaborators/:collaborator supports DELETE: https://github.com/gogs/gogs/blob/master/internal/route/api/v1/api.go#L270 but is not documented: https://github.com/gogs/docs-api/blob/master/Repositories/Collaborators.md

Add docs for `/:owner/:repo/git/tree`

See gogs/gogs#5937

How to get Account Expiration Date with API

I wanna get the data Account Expiration date with API? How can I get it ?

/api/v1/ get 404

Gogs Version: 0.11.86.0130
When I try to use rest api from gogs, I cannot use the api. the url : http://{my gogs domain}/api/v1/ got 404 error. Should I enable this feature in somewhere?

How to obtain member information of organizations through the api interface ?

How to obtain member information of organizations through the api interface ?

Git Trees API without path parameter!

Git Trees

param:
    owner
    repo
    sha(ref)

GET /repos/:owner/:repo/git/trees/:sha

The API only get root dir. but the sub directory can not get tree list. Here is github api:

param:
    owner
    repo
    ref
    path

https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}${path.replace(/^\//, ':')}

it can not get a sub-tree.

API returns Unauthorized on some endpoints

when trying to retrieve a list of available repositories for the authenticated Users, the API returns
(I've just removed the real address to avoid issues, but of course the host isn't localhost)

401: Unauthorized
r = requests.get('https://localhost/api/v1/repos/search?q=test&uid=1', auth=a, verify=False)
r
<Response [200]>
r.json()
{u'ok': True, u'data': [{u'website': u'', u'forks_count': 0, u'updated_at': u'2020-04-24T09:27:50Z', u'private': True, ...

r = requests.get('https://localhost/api/v1/user/repos', auth=a, verify=False)
r
<Response [401]>
r.reason
'Unauthorized'

I'm running mixed User configurations with LDAP connected, might this be an issue ? (naa just tried it with a local created user as well ... fails)
Fetched the latest container today with following informations

0.12.0+dev
Git-Version
2.24.1
Go-Version
go1.14.2
Build-Zeit
2020-04-21 10:12:22 UTC
Build-Commit
4e1f38ce28e87ece15a29c1f0fa2d7b5eeef79a6

Image header
"Created": "2020-04-21T10:22:42.165889729Z",
"Id": "sha256:e69e22eb6cdaed593a443876d5ec766a885637d2678a24c93c833920b5eb80a3"

Get list of Git tags

About basic authentication.

hi
i wan to create a access key ,
but response is 401 mean not authority.
i know u have written notes
Create a access token requires that you are authenticated via basic authentication.

how can i do it?
i use postman.

thank u very much!

about git data trees question

hello
i user api like http://localhost:10080/api/v1/repos/yangtianlei/test/git/trees/713879bffb203039fb263519dd443daf3e9c1484?token=713879bffb203039fb263519dd443daf3e9c1484

Response：
{
"message": "exit status 128 - fatal: not a tree object\n",
"url": "https://github.com/gogs/docs-api"
}

I don’t know where is the problem?
Please tell me how to solve this problem！
thank you ！

Have some questions about using API ...

Hello! i'm looking around community where i can ask a question, but i didn't find..
maybe this page is available to asking.. if I did a mistake, please forgive me.
and sorry for my bad english!! i will study english more..

by the way, I'm checking gogs for managing our projects!

We need to have access control function for each git repository,
and we thought gogs is perfect answer.

for more efficiency, we are going to make automatic access control system for gogs, by using docs-api. I'm planning to make each repository will have read access team, read+wirte access team automatically.

this is my first time to using RESTful API, but some of api didn't working ..

by the CURL.EXE, i successfully used POST and GET method. for example, create a new repository, create a organization, team, list up all repositories, ... etc.

worked command::
curl -H "Content-Type: application/json" -H "Authorization: token 49289d2cbe69b8dcbc74cdbfa77a52c319ad31fe" -d "{""name"": ""newrepo"", ""private"": true}" -XPOST "http://localhost:3000/api/v1/admin/users/myeonghun.noh/repos"

but I failed for PUT method.. it didn't worked and I can't find its problem and knowing someone..

failed command::
curl -H "Content-Type: application/json" -H "Authorization: token 49289d2cbe69b8dcbc74cdbfa77a52c319ad31fe" -X PUT "http://localhost:3000/api/v1/admin/orgs/CDE-6666/teams/SW-1111-read/members/myeonghun.noh"

please help me.. T_T

/repos/xxx/hooks binding check error

gogs version: 0.14.0+dev

when calling with

curl -X POST -H "Content-Type: application/json" -d @test.json http://xxx/api/v1/repos/xxx/test/hooks?token=xxx

while test.json :

{
  "type": "gogs",
  "config": {
    "content_type": "json",
    "url": "http://xxx/hook"
  },
  "events": [
    "push"
  ],
  "active": true
}

it responses:

[
  {
    "fieldNames": [
      "Type"
    ],
    "classification": "RequiredError",
    "message": "Required"
  },
  {
    "fieldNames": [
      "Config"
    ],
    "classification": "RequiredError",
    "message": "Required"
  }
]