# Configuration Reference

The **`nmk-github`** plugin handles the configuration items listed in this page.

All of them are initiliazed with convenient default values, so that you don't need to setup them for a default working behavior. You can anyway override them in your projet if you need to fine tune the plugin behavior. [Some items](extend.md) are specifically designed to be extended by **`nmk`** projects and plugins.

## Project information

(githubUser)=
### **`githubUser`** -- user name for this Github project

| Type | Default value |
|-     |-
| str  | Resolved by {py:class}`nmk_github.info.GithubUserResolver`

User name for this Github project, deduced from remote git URL.

(githubRepo)=
### **`githubRepo`** -- repository name for this Github project

| Type | Default value |
|-     |-
| str  | Resolved by {py:class}`nmk_github.info.GithubRepoResolver`

Repository name for this Github project, deduced from remote git URL.

## Actions

(githubAction)=
### **`githubAction`** -- target Github workflow file

| Type | Default value |
|-     |-
| str  | ${PROJECTDIR}/.github/workflows/build.yml

Target workflow file containing CI job definition in reaction to push operations to the remote Github repository. This file is the output of the **{ref}`gh.actions<actionsTask>`** task.

(githubActionTemplate)=
### **`githubActionTemplate`** -- workflow file template

| Type | Default value |
|-     |-
| str  | ${BASEDIR}/templates/build.yml

Jinja template used to generate the **{ref}`${githubAction}<githubAction>`** workflow file.

(githubPythonVersions)=
### **`githubPythonVersions`** -- python versions for Github workflows manual configuration

| Type | Default value |
|-     |-
| List[str]  | []

List of python versions to be used in Github workflow (manual configuration).

(githubDetectedPythonVersions)=
### **`githubDetectedPythonVersions`** -- python versions for Github workflows detected configuration

| Type | Default value |
|-     |-
| List[str]  | Resolved by {py:class}`nmk_github.action.PythonVersionsResolver`

List of python versions to be tested in Github actions. Returns:

* **{ref}`${githubPythonVersions}<githubPythonVersions>`** if set
* otherwise if **`nmk-python`** plugin is used, the supported python versions range will be returned instead
* otherwise returns []

(githubOSImages)=
### **`githubOSImages`** -- OS images for Github actions

| Type | Default value |
|-     |-
| List[str]  | ["ubuntu-latest", "windows-latest"]

List of operating systems (build images) for Github actions

(githubCommand)=
### **`githubCommand`** -- Build command for Github actions

| Type | Default value |
|-     |-
| str  | "./buildenv.sh run nmk tests"

Command string to perform **`nmk`** build (+ tests) while running Github actions.

(githubPackageCommand)=
### **`githubPackageCommand`** -- Package command for Github actions

| Type | Default value |
|-     |-
| str  | "./buildenv.sh run nmk package"

Command string to perform **`nmk`** packaging while running Github actions.

```{note}
The packaging/publishing steps will be generated in the workflow file only if this command is not empty.

*<span style="color:green">Behavior changed in version 1.1.0</span>*
```

(githubBuildSteps)=
### **`githubBuildSteps`** -- Github build workflow steps contribution

| Type | Default value |
|-     |-
| List[Dict]  | []

A list of extra Github build workflow steps, to be executed after build command.

Expected to be a list of objects, that will be serialized in generated **{ref}`${githubAction}<githubAction>`** file.

Special keys for each object:
* **`__if__`**: when set, generate this step if the provided condition is met
* **`__unless__`**: when set, generate this step unless the provided condition is met


(githubPublishSteps)=
### **`githubPublishSteps`** -- Github publish workflow steps contribution

| Type | Default value |
|-     |-
| List[Dict]  | []

A list of extra Github publish workflow steps, to be executed after build command.

Expected to be a list of objects, that will be serialized in generated **{ref}`${githubAction}<githubAction>`** file.

Special keys for each object:
* **`__if__`**: when set, generate this step if the provided condition is met
* **`__unless__`**: when set, generate this step unless the provided condition is met

## Badges

Following items help to configure generated badges related to Github details.

(githubLicenseFile)=
### **`githubLicenseFile`** -- License file path

| Type | Default value |
|-     |-
| str  | "LICENSE"

Path to license file (relative to project directory)

(githubLicense)=
### **`githubLicense`** -- License used by Github project

| Type | Default value |
|-     |-
| str  | Resolved by {py:class}`nmk_github.info.GithubLicenseParser`

License type (by default, parsed from **{ref}`${githubLicenseFile}<githubLicenseFile>`**).

(githubIssuesRepo)=
### **`githubIssuesRepo`** -- Github repository hosting issues

| Type | Default value |
|-     |-
| str  | **{ref}`${githubRepo}<githubRepo>`**

Github repository hosting issues for this project (default to current repository).

(githubIssuesLabel)=
### **`githubIssuesLabel`** -- Github issues query optional label

| Type | Default value |
|-     |-
| str  | ""

Optional label used when querying issues for this repository.

(githubIssuesLabelSuffix)=
### **`githubIssuesLabelSuffix`** -- Github issues query optional label

| Type | Default value |
|-     |-
| str  | Resolved by {py:class}`nmk_github.info.GithubIssuesLabelResolver`

Query suffix for extra label provided by **{ref}`${githubIssuesLabel}<githubIssuesLabel>`**.