A project settings file is required for any plugin or theme that is meant to receive updates from the API. The file has to be named after the project slug passed in the api-request and located in the /projectSettings folder. projectSettings/[slug].json

The following text will describe the required and optional settings.

host

Required
Example: "host" : "github"
Value: string ("bitbucket", "github" or "[yourGitlabKey]")
This value tells the api on which remote the project is hosted.

user

Required for protected repositories.
Example: "user" : "Derp"
Value: string
The login-name of a user with read access to the project repository.
This can match a user in the global settings file so you do not have to set the password.

projectOwner

Required for bitbucket and github. (Useless for gitlab)
Example: "projectOwner" : "Xiphe"
Value: string
The login name of the projects owner. This is part of the URLs to retrieve the project files from remote. Gitlab does not need this because all repositories are directly accessable by their name if the user has access.

globalkey

Required for gitlab optional for github and bitbucket.
Example: "globalkey" : "myGitlabKey"
Value: string
Gitlab does not have a public hosted version like github and bitbucket. Therefore this setting have to match the value of [yourGitlabKey] in the global config in order to get the right URLs and userdata.
If you need another set of URLs and users for github or bitbucket. (For example if you use selfhostet enterprise github.) you can also use this value to set a different key. (Not tested)

folderName

Optional
Example: "folderName" : "my-pluginFolder"
Value: string
Requires global settings "useCache" and "renameFolders" to be set to true
By default github and bitbucket are naming the project folders containing a part of the commit sha and the username. This comes unhandy because your project will have a different foldername in the wp-content folder each time you update. Gitlab even does not wrap the project files in a folder. If the global settings "useCache" and "renameFolders" are true the folder name will be rewritten to the project slug passed in the request.
This option can be used to set a name different to the slug.

info

Optional
Example: "info" : "style.css"
Value: string
The info-file is the file containing the projects informations required by Wordpress. (For example: Theme Name, Author, Version...) by default this is [slug].php for plugins and style.css for themes.
If you use a different file you can set the path here.
Important: If you do not want to rely on the request to specify if the project is a plugin or a theme you should set this value to a .css file if project is a theme. This also means, that you can not use a css file as info-file for a plugin.

remoteSlug

Optional
Example: "remoteSlug" : "my-github-project"
Value: string
By default the requests to gitbug, bitbucket and gitlab will contain the slug passed by the api request. If the repository hosted on github etc. is named differently to this slug you need to set this setting to the url form of the repro-name.

readme

Optional
Example: "readme" : "txt/readme.txt"
Value: string
Default: "readme.md"
Setting to alter the name and/or path to the readme file.

password

Optional
Example: "password" : "1234"
Value: string
If the user is not present in the global settings you have to define the password here.

token

Optional for gitlab with cache
Example: "token" : "abc"
Value: string
If the user is not present here and you do use cache the private token of the user needs to be set here in order to provide API access to gitlab.

access

Required
Value: mixed ("*" or array of accessSettings)
This setting can be a wildcard to allow everyone to access the API for this project or an array containing one or more entry's of access settings. An Access Setting is an object containing one ore more of the following keys.

ip
string or array of strings containing ip addresses from which the access is allowed.
apikey
string or array of strings containing API-keys that have to be passed by the request in order to get access.

branch
string or array of strings containing branch names to which this access-setting has access.

Each combination of the settings will work. ONLY ONE VALUE PER OPTION HAS TO BE TRUE. An not existend key means this value will not be checked. See examples.

---

Example Access Settings

Access for everybody!!!

apikey have to be set in request anyway.

{
	// […],
	"access" : "*"
}

Full access for requests from IP-address "127.0.0.1" OR with apikey "xyz".

{
	// […],
	"access" : [
		{
			"ip" : "127.0.0.1"
		},
		{
			"apikey" : "xyz"
		}
	]
}

Access for requests from IP address "127.0.0.1" AND containing the API-key "xyz" AND targeting the branch "stable".

{
	// […],
	"access" : [
		{
			"ip" : "127.0.0.1",
			"apikey" : "xyz",
			"branch" : "stable"
		}
	]
}

Recomended

{
	// […],
	"access" : [
		{
			/* 
			 * Example wordpress installation on wp.example.org.
			 * Admin: Mr. Foo <[email protected]>
			 */
			"ip" : "127.0.0.1",
			"apikey" : "some!pretty%long_string,containing§numbers(146)and#special-chars",
			"branch" : "stable"
		},
		{
			/* 
			 * My development server.
			 * Admin: Mr. Me <[email protected]>
			 */
			"ip" : "127.0.0.2",
			"apikey" : "another,=long}string{containing>numbers[146]and*special|chars",
		}
	]
}